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, theX-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-levelerror 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.
Streaming errors
Whenstream=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.
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.Content filter during streaming
Content moderation during streaming works differently from other stream errors: there is no top-levelerror object. Instead, the stream sends a final assistant content event and then a terminal event with finish_reason: "content_filter".
Grounded streaming citations
For Grounded Completions, whenstream=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 “Checkretryable” 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 theAuthorization header is missing from the request.
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.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 as400 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 HTTP429 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:
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 HTTP402 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)
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
A503 is one of two codes. Check error.code:
2002 / PROVIDER_UNAVAILABLE: the model provider is unavailable or overloaded. Retry with exponential backoff. There is noRetry-After.3003 / SERVICE_UNAVAILABLE: a temporary problem on Gloo’s side; your request and API key were not at fault. Wait for theRetry-Afterheader (usually 30 seconds), then retry. Contact support with thetrace_idif it persists.
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 get503 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
200response with a2002 / PROVIDER_UNAVAILABLEstream error event withretryable: true, then[DONE]. - Direct streams that fail before any output get the same
503as a non-streaming request. After output has started, Direct Completions ends with a2002error chunk, then[DONE], and Direct Responses ends with aresponse.failedevent. 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.
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 shortmessage 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:
- Show
messageto your end users. - Branch on the
X-Gloo-Error-Codeheader and onretryable. - Log
developer_message,reasons, andX-Request-Idso you can investigate without contacting support. - Never parse
messageordeveloper_message. Their wording can change; the codes do not. - Retry rules:
- If
retryableisfalse, don’t resend the request unchanged. - If
retryableistrueand the response hasRetry-After, wait that many seconds before retrying. - If
retryableistrueand there is noRetry-After, waitmin(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-Afteris 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.
- If
Every error on the direct endpoints
Response bodies
Provider and platform failures (error.code is a number):
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:
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) returns400 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,
reasonscombines 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 the400above, 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.
Streaming on the direct endpoints
- Before any output is sent: you get the same status, body, and headers as a non-streaming request, for example
503 service_unavailablewithRetry-After,503 provider_unavailable,429 rate_limit,504 provider_timeout, or400 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 theerrorobject, includingdeveloper_message, andretry_afterwhen it applies), then[DONE]. See Streaming Errors. - Responses sends a
response.failedevent, as in OpenAI’s Responses streaming spec.response.statusis"failed"andresponse.error.codeis the string code (the same value asX-Gloo-Error-Code). Gloo addsgloo_code(the numeric code),developer_message,retryable, and, when they apply,reasonsandretry_after. Some streams send anerrorevent just beforeresponse.failed; itscodeis the same string code.
- Chat Completions sends an error chunk (
- 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", withreasonson that choice when categories were named. Responses ends withresponse.failedand codeprovider_content_policy_violation. - A model’s own content filter on a successful response:
finish_reason: "content_filter", withreasonson the choice when categories were named.
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
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
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
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
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
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
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 aduplicates 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 onerror.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.

