# Errors and limits

> Standard JSON error envelope, HTTP status codes, and rate limiting headers.

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:

```json
{
  "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.