Errors and retries

{
  "error": {
    "message": "Human-readable message",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_request",
    "request_id": "req_..."
  }
}

Every error uses this envelope. Branch on error.code, which is stable, and show error.message to developers, not to end users. The x-request-id response header carries the same request ID.

Decide what to do

Error codes

HTTP	`code`	Meaning	Retry?
400	`invalid_request`	The body is not valid JSON or a field is invalid	No, fix the request
400	`context_length_exceeded`	The input is longer than the model allows	No, shorten it
401	`invalid_api_key`	The key is missing or not recognized	No
401	`revoked_api_key`	The key was revoked	No, create a new key
401	`expired_api_key`	The key has expired	No, create a new key
403	`project_archived`	The project is archived	No
403	`permission_denied`	The key lacks permission for this endpoint	No, change key permissions
404	`model_not_found`	The model ID does not exist	No, use an ID from `GET /v1/models`
404	`model_not_allowed`	The model exists but this key or project cannot use it	No
405	`method_not_allowed`	The HTTP method is not supported on this path	No
429	`rate_limit_exceeded`	The project’s request or token rate limit was reached	Yes, with backoff
429	`budget_exceeded`	The request would exceed the project’s monthly budget	No, raise the budget or wait
429	`upstream_rate_limit`	The model provider’s rate limit was reached	Yes, with backoff
402	`insufficient_credits`	The model provider account has no credits	No, contact support
502	`upstream_unavailable`	The model provider is temporarily unavailable	Yes
502	`provider_auth_error`	The provider rejected its credentials	No, contact support
502	`upstream_model_not_found`	The configured upstream model was not found	No, contact support
502	`invalid_upstream_response`	The provider returned a response that could not be used	Yes, once or twice
504	`upstream_timeout`	The provider did not answer in time	Yes
5xx	`output_limit_exceeded`, `server_misconfigured`, `database_error`, `internal_error`	A Mibyan-side problem	Retry once, then contact support

A 429 is not always safe to retry. budget_exceeded also returns 429, and retrying it only repeats the failure. Check error.code, not just the status.

Retry with backoff

Retry only rate_limit_exceeded, upstream_rate_limit, upstream_unavailable, and upstream_timeout, with exponential backoff and jitter. Never retry authentication, permission, archived-project, invalid-request, or model-restriction errors without changing the request or configuration.

import random, time

def call_with_retry(send, attempts=5):
    for n in range(attempts):
        resp = send()
        if resp.status_code < 400:
            return resp
        code = resp.json().get("error", {}).get("code")
        retryable = code in {
            "rate_limit_exceeded", "upstream_rate_limit",
            "upstream_unavailable", "upstream_timeout",
        }
        if not retryable or n == attempts - 1:
            resp.raise_for_status()
        time.sleep(min(30, 2 ** n) + random.random())

Rate limit headers

Responses include headers that show how much of your project’s limit is left:

Header	Meaning
`x-ratelimit-limit-requests` / `x-ratelimit-remaining-requests`	Request limit and what remains
`x-ratelimit-limit-tokens` / `x-ratelimit-remaining-tokens`	Token limit and what remains
`x-ratelimit-reset-requests` / `x-ratelimit-reset-tokens`	When the window resets

Slow down before remaining reaches zero instead of waiting for a 429.

Contact support with the request ID

Include the x-request-id value (it looks like req_...) when you contact support. It ties your report to the exact request in Platform logs.

Guides

Endpoints

Decide what to do

Error codes

Retry with backoff

Rate limit headers

Contact support with the request ID

​Decide what to do

​Error codes

​Retry with backoff

​Rate limit headers

​Contact support with the request ID

Decide what to do

Error codes

Retry with backoff

Rate limit headers

Contact support with the request ID