Skip to main content
Error handling depends on whether the response is non-streaming or streaming. For non-streaming responses, check the HTTP status code and parse the JSON response body. Streaming Completions responses start as 200 text/event-stream; once streaming has started, later failures arrive as Server-Sent Events instead of non-2xx HTTP responses. On the direct endpoints, a stream that fails before any output gets a real HTTP status instead; see Streaming on the direct endpoints. For AI error objects, error.code is the numeric internal code, such as 2001, and error.name is the symbolic code, such as PROVIDER_TIMEOUT. On this page, “the direct endpoints” means Direct Chat Completions (/ai/v2/direct/chat/completions) and Direct Responses (/ai/v2/direct/responses). Direct Embeddings has its own errors; see Embeddings.

Quick reference

How to read an error

HTTP status codes, the AI error object, and how errors arrive after an SSE stream has started.

Error code reference

Every error code with its HTTP status, whether to retry, and what to do.

Errors by status

Authentication, validation, rate limiting, payment required, and server errors, with example bodies, including how a 402 differs from a 429.

Direct endpoint errors

The error contract for /ai/v2/direct/*: end-user message, developer_message, headers, and stream behavior.

Errors by endpoint

Error details for Completions, Responses, Anthropic Messages, Embeddings, Ingestion, Content Controls, and Search.

Image generation errors

Errors from the image_generation tool on the Responses and Chat Completions endpoints.

How to read an error

Start with the HTTP status, then branch on the code in the body (on the direct endpoints, the X-Gloo-Error-Code header). When the body has a retryable field, use it to decide whether sending the same request again can succeed.

HTTP status codes

AI error object

Completions errors include an enriched top-level error object. Use it for programmatic handling instead of parsing human-readable messages.
On the direct endpoints the error object also carries developer_message, and retry_after when Gloo knows how long to wait; see Direct Endpoint Errors.
Use error.retryable for retry decisions, error.name or error.code for branching, and trace_id for debugging with support. If model inference keeps failing — for example a repeating 2013 / PROVIDER_INFERENCE_ERROR or 3001 / INTERNAL_ERROR — open a ticket through Support in Gloo AI Studio (bottom of the sidebar; see Get help) and include the trace_id from the error response. The trace_id lets us look up the exact request and resolve the issue faster.

Streaming errors

When stream=true on Completions endpoints, the response starts as 200 text/event-stream. Once the SSE headers are sent, the HTTP status can’t change, so stream-time failures are sent as SSE events. On the direct endpoints, a failure before any output is a real HTTP status instead; see Streaming on the direct endpoints. A stream error event has choices[0].finish_reason set to "error" and includes the same enriched top-level error object used by non-streaming Completions errors.
Stream-time error scenarios include provider timeout, provider rate limit, provider 5xx, provider bad request, a temporary problem on Gloo’s side (3003 / SERVICE_UNAVAILABLE, retryable), routing error, unsupported model, empty stream, provider unavailable, malformed provider SSE, connection drop, and internal platform error.
If a stream error event includes error.retryable: true, retry with exponential backoff within the retry budgets. If error.retryable is false, retry only after changing the request or model selection.
For retry ceilings, application-level continuation after partial output, and the UX decisions around interrupted streams, see Handling Streaming Failures.

Content filter during streaming

Content moderation during streaming works differently from other stream errors: there is no top-level error object. Instead, the stream sends a final assistant content event and then a terminal event with finish_reason: "content_filter".
Do not retry content-filter terminations unchanged. Adjust the user-facing workflow or request content.

Grounded streaming citations

For Grounded Completions, when stream=true, include_citations=true, and citations are available, the first SSE event may contain a citations array before model content begins. This is a normal 200 stream event, not an error.

Error code reference

Numeric codes come first, then the string codes the direct endpoints use, then the gateway and Data Engine codes. Retry? says whether sending the same request again can succeed: “No” means change the request, the model, or the account first, and “Check retryable” means read the field on the error you got.

Errors by status

Details and example bodies for each kind of failure. Where the body differs on the direct endpoints, the section says so; the full direct-endpoint list is under Direct endpoint errors.

Authentication errors

These errors mean there is a problem with your API key or its permissions.

401 Unauthorized — Missing or Invalid API Key

Returned when the Authorization header is missing from the request.
Some Completions endpoints may return an app-level response:
Search endpoints can be rejected earlier by the gateway. When the Authorization header is present but malformed or the API key is invalid, the gateway returns 403 with the forbidden code.

403 Forbidden — Insufficient Permissions

Returned when the caller is authorized but lacks permission for the requested resource or publisher, or when the gateway rejects the authorization header.
Legacy client credentials / OAuth2. If your integration still exchanges a Client ID and Secret for an access token, a 401 usually means the token expired (tokens last one hour) or lacks the required JWT claims (sub, scope). Request a new token and retry. This flow is deprecated; create an API key to avoid token expiry and refresh entirely. See Legacy: client credentials and OAuth.
For the Ingestion API, see Ingestion for what a 403 most commonly means there; for Content Controls, see Content Controls.

Validation errors (400 / 422)

These errors indicate a problem with the parameters or body of your request. 400 Bad Request signals a structurally invalid request, while 422 Unprocessable Entity signals valid JSON that fails field-level validation.

Missing Required Field

Returned when a required body field is absent. Example: model is required when specifying direct model routing for Completions V2.

Invalid Routing Configuration

Completions V2 returns this as 400 when more than one — or no — routing mechanism is specified.

Invalid Data Type

Returned when a field receives a value of the wrong type. Example: certainty expects a float.

Rate limiting (429)

An HTTP 429 can represent a Completions spending limit, the monthly API spend limit, an endpoint-specific request quota, or the model’s provider temporarily limiting requests for this model. They don’t share one response format or retry policy. For Completions endpoints, a spending-limit response has the following shape:
SPENDING_LIMIT_EXCEEDED is not retryable and does not include Retry-After. Retry only after the account’s spending-limit condition is resolved. Prepaid organizations hit their monthly API spend limit with 429 / 1009 MONTHLY_SPEND_LIMIT_REACHED instead, even when credit remains. The message begins “Your organization has reached its monthly API spend limit.”; it is not retryable, and adding credits does not clear it; access returns when the month resets (UTC) or support raises the limit. An empty balance is a different response: 402 INSUFFICIENT_CREDIT, covered under Payment Required. Endpoint-specific quotas can also return HTTP 429. Their error bodies and headers vary by endpoint. Honor Retry-After when it is present; do not assume that every response includes X-RateLimit-Limit, X-RateLimit-Remaining, or X-RateLimit-Reset. When the model’s provider is temporarily limiting requests for the model, a non-streaming request returns 429 / 2004 RATE_LIMIT with fault: "provider", retryable: true, and a Retry-After header. This is not your account’s quota, so retrying is the right response: wait for Retry-After, then retry with bounded exponential backoff. The guarded and grounded endpoints return this body:
On the direct endpoints the same case carries the shorter message “Too many requests right now. Please try again shortly.”, with the detail in developer_message and the wait in retry_after; see Direct Endpoint Errors. A provider rate limit that occurs after a Completions stream starts is not an HTTP 429. It is delivered inside the HTTP 200 stream as a 2004 / RATE_LIMIT SSE error event. Use error.retryable to decide whether to retry.
See Rate Limits for response-specific retry guidance, and Error Handling and Retries for retry pseudocode.

Payment required (402)

An HTTP 402 means the request was refused because the billing entitlement or pool that would pay for it is unavailable: an empty prepaid balance, a spent Gloo Code allowance, or no Gloo Code plan at all. It is not the monthly spend-limit response; that is 429 / 1009 MONTHLY_SPEND_LIMIT_REACHED, which can fire with credit still in the balance and clears only when the month resets or the limit is raised. The remedy depends on the code below: add credits, buy a top-up, choose a plan, or wait for the reset. See Prepaid Credits for the two limits side by side. For the inference endpoints, an exhausted prepaid balance returns:
INSUFFICIENT_CREDIT is not retryable. Add credits from the Studio Billing page and retry; access resumes as soon as the credit lands. The Gloo Code route (/ai/v2/gloocode/chat/completions) has its own two refusals with the same body shape plus a topup_available boolean at the top level:
A Gloo Code organization can hold a healthy credit balance and still receive GC_ALLOWANCE_EXHAUSTED: API credits and the Gloo Code allowance are separate pools. See Billing & Plans.

Server errors (5xx)

Retry only transient failures. For Completions errors, check error.retryable; in particular, do not retry 1005 / SPENDING_LIMIT_EXCEEDED, 1009 / MONTHLY_SPEND_LIMIT_REACHED, or 3001 / INTERNAL_ERROR. For endpoint-specific 429 responses, honor Retry-After when present and follow the endpoint’s documented behavior. Keep every retry within the retry rule.

500 Internal Server Error

An unexpected error occurred during model inference (2013 / PROVIDER_INFERENCE_ERROR, retryable: retry with exponential backoff) or on the Gloo platform (3001 / INTERNAL_ERROR, not retryable: don’t resend it unchanged, and contact support with the trace_id if it persists). On the direct endpoints a 3001 has the message “Something went wrong.”

502 Bad Gateway

Returned by Content Controls endpoints when a vector-store update fails in the underlying data store.

503 Service Unavailable

A 503 is one of two codes. Check error.code:
  • 2002 / PROVIDER_UNAVAILABLE: the model provider is unavailable or overloaded. Retry with exponential backoff. There is no Retry-After.
  • 3003 / SERVICE_UNAVAILABLE: a temporary problem on Gloo’s side; your request and API key were not at fault. Wait for the Retry-After header (usually 30 seconds), then retry. Contact support with the trace_id if it persists.
The guarded and grounded endpoints return these bodies:
On the direct endpoints both codes carry the message “The service is temporarily unavailable. Please try again.”, a developer_message, and, for 3003, retry_after; see Direct Endpoint Errors.

Every provider unavailable

If a provider can’t serve your request, Gloo tries another provider that serves the same model (Provider Failover). If every provider that serves the model was unavailable, you get 503 with 2002 / PROVIDER_UNAVAILABLE, fault: "provider", and retryable: true. If the providers failed in different ways, you get the error from the last one tried. This isn’t caused by your request or API key, so there is nothing to change on your side. Retry with exponential backoff; if it persists, try a different model or contact support with the trace_id (and X-Request-Id on the direct endpoints). Streams fail over the same way. A provider failure that arrives inside a stream, before any output has reached you, is handled like a failed request: another provider answers from the beginning. After output has started, another provider continues the answer for models that support it. When no provider can:
  • Guarded and grounded streams end inside their 200 response with a 2002 / PROVIDER_UNAVAILABLE stream error event with retryable: true, then [DONE].
  • Direct streams that fail before any output get the same 503 as a non-streaming request. After output has started, Direct Completions ends with a 2002 error chunk, then [DONE], and Direct Responses ends with a response.failed event. See Streaming on the direct endpoints.

504 Gateway Timeout

The model provider did not respond in time (2001 / PROVIDER_TIMEOUT, retryable). Retry with exponential backoff.
On the direct endpoints, the 504 for a provider timeout uses the message “The service is temporarily unavailable. Please try again.” instead of the one in the example; see Direct Endpoint Errors. Gloo’s own response deadline is a different case: 3007 / GATEWAY_DEADLINE, fault: "internal", retryable: false. A non-streaming request that runs past it gets 408 on the guarded and grounded endpoints, with the message “The request took too long to complete. Please retry with a shorter request or use streaming.” On the direct endpoints it gets 504 with code gateway_deadline, so check the error code rather than the status alone. Sending the same request again meets the same deadline: stream long generations, or lower the output limit or the reasoning effort.

Direct endpoint errors

Direct Chat Completions (/ai/v2/direct/chat/completions) and Direct Responses (/ai/v2/direct/responses) use the error contract in this section. Their error codes mean the same as on the other Gloo AI endpoints. Direct Embeddings does not use this contract; see Embeddings.

One message for your users, the rest for you

Every direct-endpoint error carries a short message that is safe to show to an end user as is, and separate fields for you to work out what happened: Every direct-endpoint error response also has these headers: How to use them:
  1. Show message to your end users.
  2. Branch on the X-Gloo-Error-Code header and on retryable.
  3. Log developer_message, reasons, and X-Request-Id so you can investigate without contacting support.
  4. Never parse message or developer_message. Their wording can change; the codes do not.
  5. Retry rules:
    • If retryable is false, don’t resend the request unchanged.
    • If retryable is true and the response has Retry-After, wait that many seconds before retrying.
    • If retryable is true and there is no Retry-After, wait min(2^(attempt-1), 30) seconds plus jitter, up to 5 requests in total for background work, or 2 retries with short backoff when someone is waiting.
    • If Retry-After is longer than the caller can wait, don’t wait: fail fast with a clear message, or defer the work to a background job. See the retry rule.

Every error on the direct endpoints

Response bodies

Provider and platform failures (error.code is a number):
Headers: X-Gloo-Error-Code: service_unavailable, Retry-After: 30, X-Request-Id. Refusals (authentication, access, content policy, unknown path or method) use a detail object with a string code:
Billing refusals (402 INSUFFICIENT_CREDIT, 429 SPENDING_LIMIT_EXCEEDED, 429 MONTHLY_SPEND_LIMIT_REACHED) keep the bodies shown under Payment Required and Rate Limiting, with a developer_message added to the error object. The two account-setup refusals (organization required, no billing account) keep their plain-text detail and add a top-level developer_message. So do request-validation 422 responses, beside their detail list. For when a content-policy refusal is retried on another provider first, see Content Policy Refusals.

Content policy refusals (direct endpoints)

On the direct endpoints, when the model provider declines a request under its content policy, a non-streaming request (or a stream that fails before any output) returns 400 with this body and the header X-Gloo-Error-Code: provider_content_policy_violation:
reasons lists the categories the provider flagged, as short lower-case names. It never contains your prompt text, and it is present only when the provider named categories; the “Flagged” sentence in developer_message appears only then too. After output has started, a Direct Completions stream ends with a content-filter termination, with reasons on the choice when categories were named, and a Direct Responses stream ends with a response.failed event whose error.code is provider_content_policy_violation. This includes moderation and guardrail blocks from a provider that screens requests before the model sees them: they return this 400, not a retryable provider error, and are not retried except as described below. Before you get this answer, Gloo handles the refusal according to where it came from:
  • A provider’s moderation layer refused the prompt (it screens the prompt before any model sees it). Gloo tries the request once more on a different provider that serves the same model, never on the provider that refused. If that provider answers, you get its answer. If it refuses too, or fails, you get the content-policy refusal; when both refused, reasons combines their categories. This happens only when the provider refuses the request outright, before its stream starts. A refusal that arrives inside the provider’s stream is not tried on another provider: before any output you get the 400 above, and after output has started the stream ends as described above.
  • A provider-side guardrail blocked the request, or the model itself refused. The refusal is final: Gloo returns it at once, without trying another provider.
A content-policy refusal is about the request, so sending the same request again fails the same way. Rephrase the request or choose a different model; do not retry it unchanged.

Streaming on the direct endpoints

Behavior change. A streamed request on a direct endpoint used to start with 200 even when it failed before any output, and the failure arrived as an SSE error event. A failure before any output is now a real HTTP status. If your client assumes a stream always starts with 200, check the status first.
  • Before any output is sent: you get the same status, body, and headers as a non-streaming request, for example 503 service_unavailable with Retry-After, 503 provider_unavailable, 429 rate_limit, 504 provider_timeout, or 400 provider_content_policy_violation. OpenAI SDKs raise it as an API error.
  • After output has started: the status is already 200, so the failure arrives in the stream.
    • Chat Completions sends an error chunk (finish_reason: "error" and the error object, including developer_message, and retry_after when it applies), then [DONE]. See Streaming Errors.
    • Responses sends a response.failed event, as in OpenAI’s Responses streaming spec. response.status is "failed" and response.error.code is the string code (the same value as X-Gloo-Error-Code). Gloo adds gloo_code (the numeric code), developer_message, retryable, and, when they apply, reasons and retry_after. Some streams send an error event just before response.failed; its code is the same string code.
  • Content policy after output has started: Chat Completions ends with the text “This request couldn’t be completed. Please rephrase it and try again.”, then finish_reason: "content_filter", with reasons on that choice when categories were named. Responses ends with response.failed and code provider_content_policy_violation.
  • A model’s own content filter on a successful response: finish_reason: "content_filter", with reasons on the choice when categories were named.
The example below is trimmed: the real event carries more fields, such as created_at.

Errors by endpoint

What each endpoint family adds to the errors above, with example bodies. Each section links the endpoint’s API reference.

Completions V2

Completions V2 Reference

POST /ai/v2/guarded/chat/completions
The endpoint reference documents both application/json responses for non-streaming requests and text/event-stream responses for stream=true.

Grounded Completions

Grounded Completions Reference

POST /ai/v2/grounded/chat/completions
Grounded Completions inherits all Completions V2 error responses, including routing configuration errors, context length exceeded, provider timeout, content filter, inference error, and provider unavailable. The endpoint reference documents both application/json responses for non-streaming requests and text/event-stream responses for stream=true. For streaming grounded responses, citations may be emitted as the first stream event when include_citations=true. Zero results is not an error — no retrieved content was relevant enough to use. The response returns 200 OK with "sources_returned": false. Check that rag_publisher names the right publisher and that its content has been ingested.

Direct Completions

Direct Completions Reference

POST /ai/v2/direct/chat/completions
Direct Completions follows the direct endpoint error contract: every error has an end-user message, a developer_message, and an X-Gloo-Error-Code header. It does not run guardrails or routing, so the guarded-only cases in Completions V2, such as the routing-configuration error, do not apply. The cases you are most likely to handle: With stream=true, a failure before any output gets the same status and body as above; after output has started, it arrives as an SSE error event. See Streaming on the direct endpoints.

Responses

Guarded Responses

POST /ai/v2/guarded/responses

Direct Responses

POST /ai/v2/direct/responses

Grounded Responses

POST /ai/v1/grounded/responses
The Responses endpoints share the platform-wide errors above (401, 403, 402, 429, 5xx). Direct Responses follows the direct endpoint error contract, with the same errors as Direct Completions, and ends a stream that fails after output has started with a response.failed event. The cases below are specific to Responses. With stream=true: on the guarded and grounded endpoints, errors after the stream has started are delivered as SSE events instead of HTTP status codes; see Streaming errors. On Direct Responses, a stream that fails before any output gets a real HTTP status, and one that fails after output has started ends with response.failed; see Streaming on the direct endpoints.

Anthropic Messages

The Anthropic Messages endpoint (POST /ai/v2/direct/anthropic/v1/messages) uses Anthropic’s error shape instead of the bodies on this page, so the Anthropic SDKs raise their usual exception classes and apply their usual retry rules. Its statuses, error.type values and retry headers are listed under Errors in the Anthropic Messages guide.

Embeddings

Direct Embeddings Reference

POST /ai/v2/direct/embeddings
Embeddings request-validation errors use a detail object with message, type, code, retryable, and, when applicable, param. Provider errors use the enriched top-level error object. Authentication and billing errors use the bodies under Authentication Errors, Payment Required, and Rate Limiting. Direct Embeddings errors don’t carry developer_message or the X-Gloo-Error-Code header.

Ingestion

Ingestion V2 Reference

POST /ingestion/v2/files
A 403 from the Ingestion API most commonly means the publisher_id doesn’t belong to your organization, or the item you are referencing does not belong to the specified publisher.

Duplicate upload results

Files that were already ingested come back in a duplicates array in a 200 OK response; this is not an HTTP error, and duplicates are not returned as a 409 Conflict error.

Content Controls (Data Engine)

Single Item Patch

PATCH /engine/v2/item

Multi-Item Patch

PATCH /engine/v2/items

Delete Items

DELETE /engine/v2/items

Get Item Metadata

GET /engine/v2/items/

Get Item by Producer ID

POST /engine/v2/publisher//items/by-producer
Publisher not found and invalid collection cases return 400, not 404; see Ingestion and Search and Recommendations.

Search and Recommendations

Search

POST /ai/v1/data/search

Recommendations

POST /ai/v1/data/items/recommendations/base
Zero results is not an error — it means no content exceeded the certainty threshold. Lower certainty toward 0.5 or verify that content has been ingested.

Image generation errors

Generated images are returned on the Responses endpoints, not on Chat Completions; see Image generation tool. The errors below apply on every Responses and Chat Completions endpoint, guarded, grounded, and direct. A tool that names the retired gpt-image-1 is not an error: it runs on gpt-image-2 and the response carries redirect headers.

Handling errors

Branch on error.retryable, log error.name, error.code and trace_id, retry only transient failures with backoff and jitter, and keep retries bounded. Error Handling and Retries covers non-streaming requests and Handling Streaming Failures covers streams.

Next steps

Error handling and retries

Which errors to retry, backoff with jitter, retry budgets, and what to log.

Handling streaming failures

Retry ceilings and recovery when a stream fails after output has started.

Rate limits

Spending limits, endpoint quotas, and how to stay under them.