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 30 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 for this request. 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	`OPERATION_NOT_ALLOWED`	no	Not billed	This API key is not allowed to perform this operation.
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.
413	`REQUEST_TOO_LARGE`	no	Not billed	Request is too large for this model. Shorten the input and try again.
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.

Training and datasets

The training API (/v1/accounts/{account}/...) returns the same envelope. A valid key that may not make a call — its role does not allow it, it is scoped away from the operation, or the path names an account other than its own — gets OPERATION_NOT_ALLOWED, whichever of the three it was.

Status	Code	Retry?	Billing	Message
400	`BATCH_CUSTOM_ID_DUPLICATE`	no	Not billed	Line repeats a custom_id used on an earlier line. Each line needs its own custom_id.
400	`BATCH_MODEL_UNSUPPORTED`	no	Not billed	Model '' is not available for batch jobs.
400	`DATASET_STATE_INVALID`	no	Not billed	This dataset is in state '' and does not accept that operation.
400	`INVALID_REQUEST`	no	Not billed	Invalid request: .
400	`JSONL_ENCODING`	no	Not billed	The file is not valid UTF-8 (first problem at line ).
400	`JSONL_LINE_NOT_OBJECT`	no	Not billed	Line is not a JSON object. Each line must be one complete JSON object.
400	`JSONL_MISSING_FIELD`	no	Not billed	Line is missing the required field ''.
400	`TRAINING_BASE_NOT_EXPORTABLE`	no	Not billed to you	Fine-tuning this base model produces weights that cannot be served, so this base is not offered for training.
400	`TRAINING_TOKENIZE_FAILED`	no	Not billed	The dataset could not be prepared for this base model (first problem at line ).
401	`INVALID_API_KEY`	no	Not billed	Invalid or revoked API key.
402	`INSUFFICIENT_BALANCE`	no	Not billed	Insufficient credits for this request. 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	`DATA_RESIDENCY_VIOLATION`	no	Not billed	Your organization requires data to stay in its region, so this job cannot run on an external service.
403	`OPERATION_NOT_ALLOWED`	no	Not billed	This API key is not allowed to perform this operation.
403	`PROVIDER_NOT_ALLOWED`	no	Not billed	The requested service is not available for your organization.
403	`PROVIDER_SERVICE_UNAVAILABLE`	no	Not billed	This kind of job is not available right now.
403	`TENANT_SUSPENDED`	no	Not billed	Account is suspended. Contact support or check billing status.
404	`DATASET_NOT_FOUND`	no	Not billed	Dataset '' does not exist or is not available to this account.
404	`JOB_NOT_FOUND`	no	Not billed	Job '' does not exist or is not available to this account.
404	`MODEL_NOT_FOUND`	no	Not billed	Model '' does not exist or is not available to this account.
409	`DATASET_ALREADY_EXISTS`	no	Not billed	A dataset named '' already exists in this account. Choose another id.
409	`DATASET_IN_USE`	no	Not billed	This dataset is still referenced by running jobs and cannot be deleted.
409	`IDEMPOTENCY_CONFLICT`	no	Not billed	An earlier request with the same Idempotency-Key had a different body.
409	`JOB_STATE_INVALID`	no	Not billed	This job is in state '' and does not accept that operation.
409	`MODEL_ALREADY_EXISTS`	no	Not billed	A model named '' already exists in this account. Choose another id.
413	`BATCH_TOO_LARGE`	no	Not billed	A batch can have at most lines and ; this input has lines and .
413	`DATASET_TOO_LARGE`	no	Not billed	Dataset files must be 1 GB or smaller; '' is .
429	`QUOTA_EXCEEDED`	no	Not billed	Quota '' exceeded. Request an increase or free up resources.
500	`INTERNAL`	yes	Not billed to you	An internal error occurred. Reference: .
500	`TRAINING_RUN_ABANDONED`	yes	Billed	Training could not be completed after several attempts. No further charges were made after the last completed step.
503	`STORAGE_UNAVAILABLE`	yes	Not billed	Service temporarily unavailable. 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

Integrations

Platform

Reference

Does a failed call cost me anything?

All errors

Training and datasets

​Does a failed call cost me anything?

​All errors

​Training and datasets

Does a failed call cost me anything?

All errors

Training and datasets