Errors

Every response carries an x-request-id header, including errors. Quote it when you ask us about a call — it is the only handle that reaches the whole path the request took. Error bodies follow the OpenAI shape:

{
  "error": {
    "message": "Invalid or revoked API key.",
    "type": "authentication_error",
    "code": "INVALID_API_KEY",
    "param": null
  }
}

Branch on code, not on message. Messages get reworded; codes do not — they are append-only, and a retired one is never reused.

Does a failed call cost me anything?

Almost never. Of the 28 errors below, 2 still produce a usage record:

REQUEST_CANCELLED — Request cancelled by client.
PARTIAL_RESPONSE_TIMEOUT — The response was cut off because the model timed out.

The reason is the same in both cases: the model had already produced output when the call came apart, so the tokens exist whether or not you received them. Everything else on this page is free of charge when it fails.

All errors

Status	Code	Retry?	Billing	Message
400	`CONTENT_BLOCKED_INPUT`	no	Not billed	The request was blocked by the content safety policy.
400	`CONTENT_BLOCKED_OUTPUT`	no	Not billed to you	The response was blocked by the content safety policy.
400	`CONTEXT_LENGTH_EXCEEDED`	no	Not billed	Request exceeds the model’s maximum context length of tokens.
400	`INVALID_REQUEST`	no	Not billed	Invalid request: .
400	`MEDIA_FETCH_FAILED`	yes	Not billed	Could not fetch media from the provided URL.
400	`MEDIA_UNSUPPORTED`	no	Not billed	Media type '' is not supported by model ''.
400	`MODEL_CAPABILITY_UNSUPPORTED`	no	Not billed	Model '' does not support ''.
400	`UPSTREAM_CONTENT_REJECTED`	no	Not billed to you	The request was rejected by the model’s content policy.
401	`INVALID_API_KEY`	no	Not billed	Invalid or revoked API key.
402	`INSUFFICIENT_BALANCE`	no	Not billed	Insufficient credits. Add credits to continue.
402	`PAYMENT_REQUIRED`	no	Not billed	A payment is overdue on this organization. Update the payment method to continue.
403	`AGREEMENT_REQUIRED`	no	Not billed	Your organization must accept the current terms of service before using this API.
403	`MODEL_NOT_ALLOWED`	no	Not billed	This API key is not allowed to use model ''.
403	`TENANT_SUSPENDED`	no	Not billed	Account is suspended. Contact support or check billing status.
404	`MODEL_NOT_FOUND`	no	Not billed	Model '' does not exist or is not available to this account.
409	`IDEMPOTENCY_CONFLICT`	no	Not billed	An earlier request with the same Idempotency-Key had a different body.
413	`MEDIA_TOO_LARGE`	no	Not billed	Media input exceeds the size limit (). Upload large files first and reference them by id.
429	`TENANT_BUDGET_EXCEEDED`	no	Not billed	Spending limit reached for this account.
429	`TENANT_RATE_LIMITED`	yes	Not billed	Rate limit exceeded for this account. Retry after s.
429	`UPSTREAM_RATE_LIMITED`	yes	Not billed	The model is temporarily over capacity. Retry after s.
499	`REQUEST_CANCELLED`	no	Billed	Request cancelled by client.
500	`INTERNAL`	yes	Not billed to you	An internal error occurred. Reference: .
503	`DEPLOYMENT_SCALING_UP`	yes	Not billed	The deployment is starting up. Retry after s.
503	`STORAGE_UNAVAILABLE`	yes	Not billed	Service temporarily unavailable. Please retry.
503	`UPSTREAM_UNAVAILABLE`	yes	Not billed to you	The model is temporarily unavailable. Please retry.
504	`PARTIAL_RESPONSE_TIMEOUT`	no	Billed	The response was cut off because the model timed out.
504	`REQUEST_DEADLINE_EXCEEDED`	yes	Not billed to you	The request exceeded the maximum allowed duration.
504	`UPSTREAM_TIMEOUT`	yes	Not billed to you	The model did not respond in time. Please retry.

Retry? = yes means the same request may succeed later with no change on your side. A no means something about the request or the account has to change first — retrying it unchanged will fail the same way.

Get started

Guides

Does a failed call cost me anything?

All errors

​Does a failed call cost me anything?

​All errors

Does a failed call cost me anything?

All errors