Errors

Every error is an OpenAI-shaped envelope with a stable code. The SDKs raise their usual exception classes by HTTP status; branch on code for anything finer.

Shape

json

{
  "error": {
    "message": "Your available balance is exhausted. Top up at https://gridport.ai/console/billing?topup=1 to resume.",
    "type": "billing_error",
    "code": "insufficient_balance",
    "param": null,
    "request_id": "req_01J…",
    "doc_url": "https://gridport.ai/docs/errors#insufficient_balance",
    "top_up_url": "https://gridport.ai/console/billing?topup=1"
  }
}

retryable means an automatic retry with backoff is reasonable. The SDKs retry 5xx and rate_limit_exceeded on their own, and stop when the response carries x-should-retry: false, as quota_exceeded, budget and balance refusals do.

Headers

x-should-retry: false marks a refusal that the same request cannot get past, however long you wait: a quota, budget or balance limit, an invalid key, or a malformed body. Fix the cause before sending again.

Retry-After gives the seconds to wait before a retry can succeed, on 429 rate limits and on retryable 5xx errors. Wait at least that long.

Codes

CodeHTTPTypeRetryWhat to do

invalid_api_key401authentication_errornoThe key is unknown, mistyped, was deleted or was revoked by GridPort support (the message says which; a support revoke also sets extra.revoked_by and its reason is in the organization audit log). Check the value your client sends, with no quotes or spaces, or create a new key in the console.

api_key_disabled401authentication_errornoThe key is disabled, or its project or owner is no longer active; the message says which. Re-enable it under API keys.

api_key_expired401authentication_errornoThe key passed its expiry date, or its rotation grace period ended. Use the replacement or create a new key.

ip_not_allowed403permission_errornoThe key has an IP allow-list and the request came from another address. Add the address or its CIDR block under API keys → Edit.

model_not_allowed_for_key403permission_errornoThe key has a model allow-list; the message lists the models it may call and extra.allowed_models has them as data. Add the model under API keys → Edit.

project_access_denied403permission_errornoYour account or access token cannot reach this organization or project: you are not a member, the token belongs to another organization, or a service token is not scoped to this project. Ask an owner to invite you, or use a token issued for this project.

organization_suspended403permission_errornoRequests from this organization are refused; the owner was told why. Contact support.

permission_denied403permission_errornoYour role does not allow this action, or the feature is not enabled for your organization (extra.feature names it). Ask an owner or admin for the permission, or contact us to enable the feature.

mfa_required403permission_errornoThis organization requires two-step verification for members who sign in with a password. Turn it on under Settings → Password & sessions, then reload.

scope_insufficient403permission_errornoThe key or access token lacks the scope this call needs (inference for model calls). Create one with that scope enabled.

reauth_required403permission_errornoThis action needs a fresh confirmation that it is you. Confirm with the method in extra.reauth_method (password, sign-in provider or SSO), then repeat the action. Access tokens cannot perform it; use a signed-in session.

subscription_exhausted402billing_errornoYour applicable subscription quota is exhausted under the block policy. Wait for reset or purchase another eligible plan.

insufficient_balance402billing_errornoThe available balance is exhausted, or too low to cover this request’s reserved maximum (input plus max_tokens). Top up (the message and top_up_url link to it); blocked requests resume within seconds. Lowering max_tokens helps only when the message suggests it. Top up in the console →

request_cost_cap402billing_errornoThe request’s worst-case cost (input plus max_tokens) is above this key’s per-request cap; the message gives both amounts. Lower max_tokens or raise “Max per request” under API keys → Edit.

request_too_large413invalid_request_errornoReduce request size. JSON supports gzip, br and deflate; decoded JSON is limited to 32 MiB by default.

budget_exceeded402billing_errornoA blocking budget (key, project or organization; monthly or total) cannot cover the request. The message and extra give the limit, spent, held and remaining amounts. Lower max_tokens or raise the limit; retrying before the reset will not help.

rate_limit_exceeded429rate_limit_erroryesRead error.dimension to distinguish key and organization limits. Honour retry-after and review the matching constraint.

quota_exceeded429rate_limit_errornoA fixed quota, not a per-minute rate, is used up, so retrying before it resets will not help. Check the limits in the console, or contact us to raise them.

concurrency_limit_exceeded429rate_limit_erroryesToo many requests are in flight at once for this key or organization. Lower your client's parallelism, and retry with backoff once earlier requests finish.

model_not_found404not_found_errornoUnknown model id. List /v1/models for ids and aliases.

request_not_found404not_found_errornoNo request with this ID is visible to you: it may be mistyped or belong to a project you cannot access. Copy the ID from the x-request-id header or the request log.

not_found404not_found_errornoThe resource in the path does not exist, was deleted, or is not visible to your account. Check the ID in the URL.

invalid_request_error400invalid_request_errornoThe request could not be accepted as sent. The message names the field (and param when there is one); fix the request and send it again. Retrying it unchanged will not help.

context_length_exceeded400invalid_request_errornoPrompt plus max_tokens exceeds the model's context. Shorten the input, lower max_tokens, or choose a model with a longer context.

unsupported_parameter400invalid_request_errornoThe model does not support this parameter; param names it. Remove it, or choose a model whose page lists the capability.

unsupported_file_type415invalid_request_errornoThis endpoint does not accept the body's format or Content-Type. Send JSON with Content-Type: application/json, or the file format the endpoint documents (JSONL for Batch input).

file_too_large413invalid_request_errornoThe upload or request body is above this endpoint's size limit (Batch input files: 100 MB). Split the file or send less content.

invalid_image_url400invalid_request_errornoAn image in the request could not be fetched or read. Use a publicly reachable https URL or a base64 data URL, in a format the model accepts.

content_filter400invalid_request_errornoA safety filter blocked the prompt. Rephrase the request; sending it again unchanged will be blocked again.

content_policy_violation400invalid_request_errornoThe request was rejected under the content policy. Change the content; retrying it unchanged will not help. See the Acceptable Use Policy.

data_policy_unmet403permission_errornoThe project's data policy (zero data retention, regions, private network) leaves no route for this model. Change the policy under Data governance or use a model it allows; retrying will not help.

idempotency_key_reused409invalid_request_errornoThis Idempotency-Key was already used for a different request. Send a new key with each new request; reuse a key only to retry the identical request.

idempotency_in_progress409conflict_erroryesA request with this Idempotency-Key is still being processed. Wait a moment, then retry with the same key to receive its result.

conflict409conflict_errornoThe resource already exists or changed since you read it (a name already in use, a revision that moved on). Reload, then retry against the current state or choose another name.

unauthenticated401authentication_errornoNo valid session or access token was sent, or it expired or was revoked. Sign in again, or send a current access token in the Authorization header.

invalid_credentials401authentication_errornoThe email and password, verification code or sign-in link did not match, or an enterprise sign-in expired. Check them and try again, or start the sign-in again; repeated failures lock the account for a while.

account_locked423authentication_errornoToo many failed sign-in attempts or verification codes. Wait for the time in the message (extra.retry_after_seconds), or reset your password.

email_not_verified403authentication_errornoThe account's email address is not verified yet. Open the link in the verification email, or ask for a new one on the sign-in page.

password_confirmation_required403authentication_errornoThe verification link was opened in a different browser from the one used to sign up. Enter the password chosen at sign-up to finish verifying.

totp_required401authentication_errornoThis sign-in needs a two-factor code. Enter the current code from your authenticator app, or a recovery code, and continue.

model_unavailable503model_erroryesNo route could serve the model. With error.reason no_active_route every route is switched off: choose another model, since retrying will not help until it is served again. Otherwise its routes were failing or busy: retry with backoff; the status page shows ongoing incidents.

model_retired410model_errornoThis model was retired; the catalog names its replacement. Switch to it.

model_version_retired410model_errornoThe pinned version (model@version) was retired. Call the model without a version to get its current default, or pin a version the model page lists as active.

provider_auth503upstream_erroryesA route could not authenticate upstream. Retry; contact support with the request ID if it persists.

model_not_supported400invalid_request_errornoThe route serving this model does not support the requested endpoint. Call the endpoint shown on the model page, or choose another model.

rate_limited429upstream_erroryesThe upstream is rate limited; your own limits were not reached. Honour retry-after and retry with backoff.

upstream_unavailable503upstream_erroryesThe upstream is overloaded or temporarily unavailable. Retry with backoff; the status page shows ongoing incidents.

upstream_error502upstream_erroryesEvery route failed before the first byte. Retry.

upstream_timeout504upstream_erroryesThe model did not answer within the deadline. Retry with backoff; very long inputs or outputs take longer, and streaming returns the first tokens sooner.

stream_interrupted200upstream_errornoThe stream ended early; delivered tokens are billed, the rest is not. Treat a stream without a final chunk as incomplete and retry the request.

internal_error500server_erroryesSomething failed on our side while handling the request. Retry with exponential backoff; if it keeps happening, contact support and quote the request ID.

service_unavailable503server_erroryesA service this request depends on (for example email delivery, payments or an identity provider) is temporarily unavailable. Retry shortly; the status page shows ongoing incidents.