Use the HTTP status, response body, and response headers together when handling an API failure. This guide covers the Giotto Python SDK and the OpenAI-compatible API. Their error bodies differ, but the same HTTP status can guide your first response.
At a glance
| HTTP status | What it usually means | What to do |
|---|---|---|
400 |
The request is invalid. | Correct the request body or parameters before trying again. |
401 |
Authentication failed. | Check the credential and authentication configuration. |
402 |
Insufficient by-token API credits. | Check the balance and purchase more credits before sending a new request. |
403 |
The credential is not allowed to use this route, model, or priority. | Check access and entitlement; retry only after the configuration changes. |
404 |
The requested resource or model was not found. | Check the URL, request ID, or model identifier. |
429 |
A request-per-minute or concurrency limit was reached. | Read Retry-After, wait, and reduce the rate or number of active requests. |
502, 503, 504
|
A gateway dependency or model service is unavailable or timed out. | Use bounded backoff. Check whether an earlier attempt may have started before resending a job. |
An upstream service can return other status codes or its own error body. Inspect the complete response when a status is not listed here.
How limits work
Giotto applies a configured requests-per-minute limit and a concurrency limit. The values depend on the credential and its configured priority; do not assume a universal numeric limit. Read the limit headers on your responses and leave capacity for other workers using the same credential.
-
Requests per minute: the gateway counts requests in one-minute windows. When the count is over the configured limit, the request receives
429. Rejected attempts can still count toward the minute's observed request count, so repeatedly probing the API can make the situation worse. -
Concurrency: the gateway limits work in progress. A request may wait briefly for a slot; if no slot becomes available within the configured wait, it receives
429. A concurrency rejection may already have consumed one request from the minute's allowance. - Asynchronous orchestration: an admitted orchestration request can keep its concurrency slot after the initial HTTP response, until the job reaches a terminal event. The SDK's result-fetch polling is rate-limited separately and does not acquire another orchestration concurrency slot.
If an account has more than one credential or uses both API paths, avoid assuming that each process has its own allowance. Coordinate request volume across your integration and use the headers returned by the path you call.
Rate-limit response headers
HTTP header names are case-insensitive. These headers describe the gateway's admission decision; availability varies by API path and by how far a request got before it failed.
| Header | Meaning |
|---|---|
X-RateLimit-Limit |
Configured requests-per-minute limit for the applicable request path. |
X-RateLimit-Remaining |
Requests left in the current minute after this admission attempt. It can be 0 on a 429. |
X-RateLimit-Concurrency-Limit |
Maximum concurrent requests or jobs in the applicable concurrency pool. |
X-RateLimit-Concurrency-Used |
Number of slots in use when the gateway made its admission decision. |
X-RateLimit-Concurrency-Remaining |
Slots left at that moment. This is a snapshot, not a reservation for a future request. |
X-RateLimit-Concurrency-Scope |
Concurrency pool scope when this header is supplied by the orchestration gateway. |
Retry-After |
Seconds to wait before trying again after a gateway 429. Follow this value when present. |
The OpenAI-compatible path also returns X-Gateway-Priority and X-Gateway-Configured-Requests-Per-Minute on admitted responses. The orchestration path uses X-Gateway-Effective-Priority. These are diagnostic values; use X-RateLimit-* for the current limit and usage. There is no documented reset-time header, so do not infer a reset timestamp from X-RateLimit-Remaining.
When a limit is exceeded
A gateway rate-limit rejection uses HTTP 429 and a Retry-After header. For a requests-per-minute rejection, the header points to the next minute window. For a concurrency rejection, it gives a configured retry delay; the slot may become available sooner or later depending on active work.
OpenAI-compatible API
Rate-limit errors use an OpenAI-style error object. Check error.code to distinguish requests_per_minute from concurrency_limit_exceeded. A gateway object may also include limit, observed, and retry_after_seconds. Example values below are illustrative:
HTTP/1.1 429 Too Many Requests
Retry-After: 18
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Content-Type: application/json
{
"error": {
"message": "The requests-per-minute limit has been reached.",
"type": "rate_limit_error",
"param": null,
"code": "requests_per_minute"
},
"gateway": {
"limit": 60,
"observed": 61,
"retry_after_seconds": 18
}
}For a concurrency rejection, expect X-RateLimit-Concurrency-Limit, X-RateLimit-Concurrency-Used, and X-RateLimit-Concurrency-Remaining instead of the per-minute remaining header.
Giotto orchestration API and Python SDK
The orchestration gateway returns detail and reason fields. The rate-limit reasons are requests_per_minute and concurrency_queue_timeout. It also includes priority, limit, observed, and retry_after_seconds. Example:
HTTP/1.1 429 Too Many Requests
Retry-After: 5
X-RateLimit-Concurrency-Limit: 20
X-RateLimit-Concurrency-Used: 20
X-RateLimit-Concurrency-Remaining: 0
Content-Type: application/json
{
"detail": "Gateway rate limit exceeded",
"reason": "concurrency_queue_timeout",
"priority": 3,
"limit": 20,
"observed": 20,
"retry_after_seconds": 5
}A disabled priority can also appear as a 429 with reason: "priority_disabled" on this path. Waiting alone will not fix it; contact the account administrator or Giotto support. On the OpenAI-compatible path, a disabled priority is a 403 with error.code: "priority_disabled".
Other error codes you may see
The OpenAI-compatible gateway uses error.code for these gateway-generated errors:
| Status | error.code |
Action |
|---|---|---|
400 |
invalid_model_request |
Fix the JSON body or model field identified in the message. |
401 |
invalid_api_key |
Check the credential and Authorization header. |
402 |
insufficient_credits |
Check your by-token balance. See API billing, credits, and usage. |
403 |
priority_disabled, model_pricing_unavailable, model_unavailable_for_this_credential
|
Check the credential's enabled access and selected model. |
404 |
model_not_found |
Use a model deployed on the selected gateway. |
429 |
requests_per_minute, concurrency_limit_exceeded
|
Follow Retry-After and adjust request volume. |
502, 504
|
upstream_unavailable, upstream_timeout
|
Retry with care after checking whether work may have started. |
503 |
keycloak_unavailable, priority_store_unavailable, priority_not_configured, concurrency_store_unavailable
|
Pause requests and retry with backoff. Escalate if the condition persists. |
The orchestration gateway uses reason for some local errors: conflicting_model_selectors (400), insufficient_credits (402), api_client_route_not_allowed or unknown_or_inactive_api_client (403), and by_token_metering_unavailable_for_route (503). Authentication failures and errors returned by an upstream service may have a different body, so do not assume every response contains reason.
Retry safely
- For
429caused byrequests_per_minuteor concurrency, wait at least the number of seconds inRetry-After. Add a small random delay when many workers may retry together. Keep a maximum attempt count and an overall deadline. - For
502,503,504, or a network failure, use exponential backoff with jitter and a cap. For job-creatingPOSTrequests, first check whether the earlier attempt returned a request ID or may have reached the server; blindly resending can create duplicate work. - For
400,401,402,403, or404, correct the request, credentials, balance, or access before retrying. Treatpriority_disabledas a configuration issue even if the orchestration path reports429. - Limit work in progress in your own application. When
X-RateLimit-RemainingorX-RateLimit-Concurrency-Remainingapproaches zero, slow new submissions rather than waiting for a burst of failures.
The Python SDK raises GiottoAPIError for API failures and GiottoAuthError for authentication failures. A local GiottoTimeoutError means the SDK stopped waiting for a terminal orchestration event; it does not by itself prove that the server-side job failed. SDK API error messages include the HTTP status and body, but the SDK does not expose response headers on every API error. If your retry policy needs Retry-After, use a transport that exposes response headers or add that handling around the underlying HTTP request. The SDK does not make every failed API request safe to resend automatically.
When contacting support
Include the API path, UTC time, HTTP status, error code or reason, relevant response headers, and the orchestration request ID if one was returned. Do not send your client secret or a full Authorization header. Contact Giotto support if a service error persists or your configured limit appears incorrect.
Comments
0 comments
Please sign in to leave a comment.