Errors and limits

All REST API errors return within a standard JSON envelope accompanied by standard HTTP status codes.

Error envelope structure

When an API call fails, the response payload contains an error dictionary:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "4b68e210ac124b868e826b5278c5208f",
    "details": {}
  }
}

Envelope attributes:

• code: machine-readable error token string.
• message: human-readable description of the error.
• request_id: unique trace identifier matching the X-Request-ID HTTP response header.
• details: object holding supplementary contextual attributes.

HTTP status codes

Status	Meaning	Typical code values
400 Bad Request	Malformed JSON body or invalid request parameters.	invalid_cloud_request, invalid_source_metadata, invalid_pagination
401 Unauthorized	Missing, malformed, or invalid API key.	invalid_api_key, authentication_required
402 Payment Required	Storage quota ceiling reached.	insufficient_quota
403 Forbidden	Key lacks required scope or operation is restricted.	insufficient_scope, agent_sync_not_allowed, tenant_owner_required
404 Not Found	Requested route, file, or key does not exist.	not_found
409 Conflict	Object state collision during processing.	conflict
429 Too Many Requests	Rate limit threshold exceeded on metadata endpoints.	rate_limit_exceeded
503 Service Unavailable	Storage gateway or backend service is temporarily offline.	cloud_unavailable

Rate limiting headers

Metadata endpoints enforce a limit of 120 calls per minute per API key.

When an HTTP 429 response is issued, the server supplies the following HTTP headers:

• Retry-After: waiting interval in seconds before retry attempts are accepted.
• RateLimit-Limit: maximum allowed calls in the fixed minute window (120).
• RateLimit-Remaining: remaining quota balance within the window (0).
• RateLimit-Reset: Unix timestamp in seconds marking window renewal.