Errors - Gloo

When interacting with the Gloo AI API, 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. For streaming Completions responses, the initial response is 200 text/event-stream; once streaming has started, later failures are delivered as Server-Sent Events instead of non-2xx HTTP responses. 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.

Quick Reference

HTTP Status Codes

Full table of every HTTP status returned by active endpoints.

Error Code Reference

Exact error codes from the API with resolution guidance.

AI Error Object

Field reference for enriched Completions errors.

Streaming Errors

How errors are delivered after an SSE stream has started.

Authentication Errors

401 and 403 errors — missing tokens, expired credentials, permission issues.

Rate Limiting

Spending limits, endpoint quotas, and streaming provider rate limits.

Endpoint-Specific Errors

Error details for Completions, Ingestion, Content Controls, and Search.

Best Practices

Patterns for reliable error handling across all endpoints.

HTTP Status Codes

Status Code	Meaning	When You’ll See It
`200 OK`	Success	The request completed successfully.
`400 Bad Request`	Bad Request	Missing required fields, wrong content type, or structurally invalid JSON.
`401 Unauthorized`	Unauthorized	`Authorization` header missing, token expired, or required JWT claims (`sub`, `scope`) absent.
`403 Forbidden`	Forbidden	Authorization was present but invalid, insufficient, or not allowed for the resource or publisher.
`404 Not Found`	Not Found	Requested resource (item, publisher, collection) does not exist or was deleted.
`408 Request Timeout`	Request Timeout	Model provider did not respond within the allowed window. Retry with backoff.
`422 Unprocessable Entity`	Validation Error	Well-formed JSON that fails semantic validation — invalid enum, out-of-range value, business rule violation.
`429 Too Many Requests`	Limit Reached	A Completions spending limit or an endpoint-specific request quota was reached. Inspect the response before retrying; some `429` errors are not retryable.
`500 Internal Server Error`	Server Error	Unexpected error on the Gloo platform. Retry with backoff.
`502 Bad Gateway`	Upstream Error	Returned when a Content Controls vector-store update fails.
`503 Service Unavailable`	Service Unavailable	Gloo service or upstream provider temporarily unavailable. Retry with backoff.

Error Code Reference

Code / Name	HTTP Status	Description	Resolution
`unauthorized_missing_authorization`	401	`Authorization` header is absent.	Add `Authorization: Bearer <your-api-key>` to all requests.
`forbidden`	403	Authorization was present but invalid, insufficient, or not allowed for the resource or publisher.	Verify the API key value; check scopes and publisher access.
`publisher_not_found`	400	Publisher ID does not exist.	Verify the `publisher_id` value in the request.
`publisher_mismatch`	403	Item does not belong to the specified publisher.	Check that the `publisher_id` matches the item’s original publisher.
`item_not_found`	404	Requested item does not exist or was deleted.	Verify `item_id` or `producer_id`. Use list endpoints to confirm existence.
`item_publisher_mismatch`	403	Item does not belong to the specified publisher.	Verify `publisher_id` and `item_id` belong to the same publisher.
`too_many_files`	400	Producer ID is per-file only; multiple files submitted.	Submit one file per `producer_id`.
`file_read_error`	400	Uploaded file could not be decoded or read.	Verify the file is valid and not corrupt before uploading.
`missing_producer_ids`	400	No `producer_id` values provided.	Include at least one `producer_id` in the request.
`duplicate_content`	200 result state	Content already ingested. Public response exposes the `duplicates` array alongside `ingesting`.	No action needed if re-ingestion is unintentional. To update, delete or patch the existing item.
`validation_error`	422	One or more fields failed semantic validation.	Inspect the `detail` array: `loc` = field path, `msg` = reason, `input` = value you sent.
`1001 / INVALID_REQUEST`	400	Request is structurally invalid — missing user message or invalid routing configuration.	Fix the request body; for Completions V2, specify exactly one routing mode (`auto_routing`, `model`, or `model_family`).
`1002 / CONTEXT_LENGTH_EXCEEDED`	400	Input exceeds model’s maximum context window.	Shorten message history, reduce system prompt, or switch to a model with a larger context window.
`1003 / UNSUPPORTED_MODEL`	400 or stream event	Requested model is not recognized or unavailable in this environment.	Use a supported model from the Models endpoint.
`1005 / SPENDING_LIMIT_EXCEEDED`	429	The account’s spending limit was reached.	Check billing limits; retry only after the limit condition is resolved.
`2001 / PROVIDER_TIMEOUT`	408 or stream event	Model provider did not respond in time.	Retry with exponential backoff; consider a different model or routing mode if persistent.
`2002 / PROVIDER_UNAVAILABLE`	503 or stream event	Provider or backing service unavailable.	Retry with exponential backoff.
`2003 / CONNECTION_ERROR`	Stream event	Connection to the upstream provider was lost after streaming started.	Retry if `error.retryable` is `true`.
`2004 / RATE_LIMIT`	Stream event	Upstream provider rate limit was reached after streaming started.	Retry with bounded exponential backoff only if `error.retryable` is `true`.
`2005 / PROVIDER_CONTENT_FILTER`	422 or content-filter stream event	Provider moderated the response.	Adjust the request or user-facing workflow; do not retry unchanged.
`2007 / EMPTY_STREAM`	Stream event	Provider opened a stream but delivered no content chunks.	Retry with exponential backoff.
`2008 / PROVIDER_BAD_REQUEST`	Stream event	Upstream provider rejected the request after streaming started.	Inspect the request and model requirements; retry only after correcting the request.
`2011 / MALFORMED_SSE`	Stream event	Upstream provider sent a malformed SSE frame.	Retry with exponential backoff.
`2013 / PROVIDER_INFERENCE_ERROR`	500	Unexpected model inference failure.	Retry with exponential backoff and log `trace_id` if present in the response.
`3001 / INTERNAL_ERROR`	500 or stream event	Unexpected error. The same code covers both retryable provider anomalies (`fault: "provider"`, `retryable: true`) and non-retryable platform errors (`fault: "internal"`, `retryable: false`).	Branch on `error.retryable` and `error.fault`, never on the code alone; log `trace_id`.
`3003 / PROVIDER_AUTH_ERROR`	Stream event	Upstream provider credentials are misconfigured.	Treat as a platform issue; log `trace_id` and contact support if persistent.
`3004 / ROUTING_ERROR`	Stream event	Platform routed the request to an endpoint that does not recognize the model.	Try a different model or routing mode; log `trace_id` if persistent.

AI Error Object

Completions errors include an enriched top-level error object. Use it for programmatic handling instead of parsing human-readable messages.

{
  "error": {
    "message": "The provider did not respond in time. Please try again.",
    "type": "timeout_error",
    "code": 2001,
    "name": "PROVIDER_TIMEOUT",
    "category": "provider_error",
    "description": "The upstream model provider did not respond within the allowed time window.",
    "fault": "provider",
    "retryable": true,
    "trace_id": "trace-id"
  }
}

Field	Description
`message`	Request-specific customer-facing error message.
`type`	Stable wire-format error type.
`code`	Numeric internal error code.
`name`	Symbolic error name for programmatic branching and alerting.
`category`	Broad category: `client_error`, `provider_error`, or `platform_error`.
`description`	Stable explanation of what the error code means.
`fault`	Responsible party: `client`, `provider`, or `internal`.
`retryable`	Whether retrying the same request may succeed.
`trace_id`	Trace identifier to include in support requests when present.

Use error.retryable for retry decisions, error.name or error.code for branching, and trace_id for debugging with support.

Hitting persistent inference issues? If model inference keeps failing — for example a repeating 2013 / PROVIDER_INFERENCE_ERROR or 3001 / INTERNAL_ERROR — open a ticket with us at hello@gloo.us and include the trace_id from the error response. The trace_id lets us look up the exact request and resolve the issue faster.

Common Error Scenarios

Authentication Errors

These errors occur when there is an issue with your API key or the permissions associated with it.

401 Unauthorized — Missing or Invalid API Key

Returned when the Authorization header is missing from the request.

{
  "error": "Missing Authorization",
  "code": "unauthorized_missing_authorization"
}

Some Completions endpoints may return an app-level response:

{
  "detail": "Invalid API key."
}

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 request includes authorization, but the caller does not have permission for the requested resource or publisher, or the gateway rejects the authorization header.

{
  "error": "Forbidden - insufficient permissions",
  "code": "forbidden"
}

For the Ingestion API, a 403 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.

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.

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "model"],
      "msg": "Field required",
      "input": {}
    }
  ]
}

Invalid Routing Configuration

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

{
  "detail": "Exactly one routing mechanism (auto_routing, model, or model_family) must be specified."
}

Invalid Data Type

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

{
  "detail": [
    {
      "type": "float_parsing",
      "loc": ["body", "certainty"],
      "msg": "Input should be a valid number",
      "input": "high"
    }
  ]
}

Resource Not Found (404)

Returned when the requested item does not exist or has been permanently deleted.

{
  "code": "Item not found",
  "item_id": "c68c9303-9851-476e-96af-aa5bdd385811",
  "message": "The requested item does not exist or has been permanently deleted"
}

Publisher not found and invalid collection cases return 400, not 404. See Ingestion and Search & Recommendations for these examples.

Duplicate Upload Results

Duplicate Content (Ingestion)

When files are submitted that were already ingested, the API returns 200 OK with a duplicates array in the response body — this is not an HTTP error.

{
  "success": true,
  "message": "File processing started in background.",
  "ingesting": [],
  "duplicates": ["c999008e-de60-495c-8c9f-6a4b59cdb04b"]
}

Duplicates are returned in the response body, not as a 409 Conflict error.

Rate Limiting (429)

An HTTP 429 can represent a Completions spending limit or an endpoint-specific request quota. These conditions do not share one response format or retry policy. For Completions endpoints, a spending-limit response has the following shape:

{
  "detail": {
    "message": "Spending limit reached",
    "code": "SPENDING_LIMIT_EXCEEDED"
  },
  "error": {
    "message": "Spending limit reached",
    "type": "billing_error",
    "code": 1005,
    "name": "SPENDING_LIMIT_EXCEEDED",
    "category": "client_error",
    "description": "The account's spending limit has been reached.",
    "fault": "client",
    "retryable": false,
    "trace_id": "trace-id"
  }
}

SPENDING_LIMIT_EXCEEDED is not retryable and does not include Retry-After. Retry only after the account’s spending-limit condition is resolved. 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. An upstream 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 pseudocode.

Server Errors (5xx)

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

500 Internal Server Error

An unexpected error occurred on the Gloo platform or during model inference. Retry with exponential backoff.

{
  "detail": "An unexpected error occurred during model inference. Please try again.",
  "error": {
    "message": "An unexpected error occurred during model inference. Please try again.",
    "type": "internal_error",
    "code": 2013,
    "name": "PROVIDER_INFERENCE_ERROR",
    "category": "provider_error",
    "description": "An unexpected error occurred during model inference at the upstream provider.",
    "fault": "provider",
    "retryable": true,
    "trace_id": "trace-id"
  }
}

502 Bad Gateway

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

{
  "detail": {
    "code": "Weaviate update failed",
    "message": "Postgres not modified due to vector store update failure",
    "weaviate_error": "Weaviate update failed"
  }
}

503 Service Unavailable

The upstream provider or backing service is temporarily unavailable. Retry with exponential backoff.

{
  "detail": "The provider is currently unavailable. Please try again later.",
  "error": {
    "message": "The provider is currently unavailable. Please try again later.",
    "type": "service_unavailable_error",
    "code": 2002,
    "name": "PROVIDER_UNAVAILABLE",
    "category": "provider_error",
    "description": "The upstream model provider is temporarily unavailable.",
    "fault": "provider",
    "retryable": true,
    "trace_id": "trace-id"
  }
}

Streaming Errors

When stream=true on Completions endpoints, the response starts as 200 text/event-stream. After the SSE headers have been sent, the API cannot change the HTTP status code. Stream-time failures are therefore sent as SSE events. 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.

{
  "id": "chatcmpl-error-abc123",
  "object": "chat.completion.chunk",
  "created": 1769792268,
  "model": "gloo-anthropic-claude-sonnet-4.6",
  "choices": [
    {
      "delta": {
        "content": null,
        "role": null
      },
      "finish_reason": "error",
      "index": 0
    }
  ],
  "error": {
    "message": "Stream connection dropped",
    "type": "connection_error",
    "code": 2003,
    "name": "CONNECTION_ERROR",
    "category": "provider_error",
    "description": "The connection to the upstream model provider was lost or could not be established.",
    "fault": "provider",
    "retryable": true,
    "trace_id": "trace-id"
  }
}

Stream-time error scenarios include provider timeout, provider rate limit, provider 5xx, provider bad request, provider auth failure, 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. 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 is represented differently from other stream errors. It does not emit a top-level error object. Instead, the stream sends a final assistant content event and then a terminal event with finish_reason: "content_filter".

{
  "id": "chatcmpl-stream-abc123",
  "object": "chat.completion.chunk",
  "created": 1769792268,
  "model": "gloo-anthropic-claude-sonnet-4.6",
  "choices": [
    {
      "delta": {
        "content": ""
      },
      "finish_reason": "content_filter",
      "index": 0
    }
  ],
  "service_tier": null,
  "usage": null
}

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.

{
  "citations": [
    {
      "item_title": "Daily Prayer",
      "item_url": "https://www.studio.ai.gloo.com",
      "author": ["John Doe"],
      "publisher": "The Publisher",
      "publication_date": "Apr 08 2017",
      "snippets": [
        "Daily prayer is an essential part of life as...",
        "Making time to spend with the Lord is..."
      ]
    }
  ]
}

Endpoint-Specific Errors

Completions V2

Completions V2 Reference

POST /ai/v2/chat/completions

The endpoint reference documents both application/json responses for non-streaming requests and text/event-stream responses for stream=true. Invalid Routing Configuration — 400 Specify exactly one of auto_routing, model, or model_family per request.

{
  "detail": "Exactly one routing mechanism (auto_routing, model, or model_family) must be specified."
}

Invalid Request — 400 Returned when no user message is found in the messages array.

{
  "detail": "No user message found in the request.",
  "error": {
    "message": "No user message found in the request.",
    "type": "invalid_request_error",
    "code": 1001,
    "name": "INVALID_REQUEST",
    "category": "client_error",
    "description": "The request is malformed or contains invalid parameters.",
    "fault": "client",
    "retryable": false,
    "trace_id": "trace-id"
  }
}

Messages Array Missing — 422 The messages field is required. An absent messages array returns a validation error.

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "messages"],
      "msg": "Field required",
      "input": {}
    }
  ]
}

Context Window Exceeded — 400

{
  "detail": {
    "message": "Input exceeds the model context window.",
    "type": "context_window_exceeded",
    "code": "context_length_exceeded",
    "model": "gloo-anthropic-claude-sonnet-4.6",
    "max_input_tokens": 1000000,
    "suggestion": "Use a model with larger context window such as gloo-anthropic-claude-sonnet-4.6 (1M tokens)"
  },
  "error": {
    "message": "Input exceeds the model context window.",
    "type": "invalid_request_error",
    "code": 1002,
    "name": "CONTEXT_LENGTH_EXCEEDED",
    "category": "client_error",
    "description": "The total token count of the request exceeds the model's context window.",
    "fault": "client",
    "retryable": false,
    "trace_id": "trace-id",
    "model": "gloo-anthropic-claude-sonnet-4.6",
    "max_input_tokens": 1000000,
    "suggestion": "Use a model with larger context window such as gloo-anthropic-claude-sonnet-4.6 (1M tokens)"
  }
}

Provider Timeout — 408

{
  "detail": "The provider did not respond in time. Please try again.",
  "error": {
    "message": "The provider did not respond in time. Please try again.",
    "type": "timeout_error",
    "code": 2001,
    "name": "PROVIDER_TIMEOUT",
    "category": "provider_error",
    "description": "The upstream model provider did not respond within the allowed time window.",
    "fault": "provider",
    "retryable": true,
    "trace_id": "trace-id"
  }
}

Provider Content Filter — 422

{
  "detail": "The provider moderated the response.",
  "error": {
    "message": "The provider moderated the response.",
    "type": "content_filter_error",
    "code": 2005,
    "name": "PROVIDER_CONTENT_FILTER",
    "category": "provider_error",
    "description": "The response was blocked by the upstream provider's content filter.",
    "fault": "provider",
    "retryable": false,
    "trace_id": "trace-id"
  }
}

Provider Inference Error — 500

{
  "detail": "An unexpected error occurred during model inference. Please try again.",
  "error": {
    "message": "An unexpected error occurred during model inference. Please try again.",
    "type": "internal_error",
    "code": 2013,
    "name": "PROVIDER_INFERENCE_ERROR",
    "category": "provider_error",
    "description": "An unexpected error occurred during model inference at the upstream provider.",
    "fault": "provider",
    "retryable": true,
    "trace_id": "trace-id"
  }
}

Provider Unavailable — 503

{
  "detail": "The provider is currently unavailable. Please try again later.",
  "error": {
    "message": "The provider is currently unavailable. Please try again later.",
    "type": "service_unavailable_error",
    "code": 2002,
    "name": "PROVIDER_UNAVAILABLE",
    "category": "provider_error",
    "description": "The upstream model provider is temporarily unavailable.",
    "fault": "provider",
    "retryable": true,
    "trace_id": "trace-id"
  }
}

Grounded Completions

Grounded Completions Reference

POST /ai/v2/chat/completions/grounded

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. No Relevant Content Retrieved — 200 Zero results is not an error — it means no retrieved content exceeded the certainty threshold. The response returns 200 OK with "sources_returned": false. Lower certainty toward 0.5 or verify that content has been ingested.

Ingestion

Ingestion V2 Reference

POST /ingestion/v2/files

Publisher Not in Organization — 403 Returned when the item or publisher does not belong to your organization.

{
  "detail": {
    "message": "Item does not belong to this publisher",
    "code": "publisher_mismatch"
  }
}

Missing Authorization — 401 Returned by the gateway when the Authorization header is missing.

{
  "error": "Missing Authorization",
  "code": "unauthorized_missing_authorization"
}

Publisher Not Found — 400

{
  "detail": {
    "message": "Publisher not found",
    "code": "publisher_not_found"
  }
}

Producer ID with Multiple Files — 400

{
  "detail": {
    "message": "Too many files. Producer ID is pre-file only.",
    "code": "too_many_files"
  }
}

File Read Error — 400

{
  "detail": {
    "message": "Could not read sermon.pdf: unable to decode uploaded file",
    "code": "file_read_error"
  }
}

Duplicate Content — 200 Response Duplicate files appear in the duplicates array of a successful 200 OK response, not as an HTTP error. See Duplicate Upload Results.

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

Item Not Found — 404

{
  "code": "Item not found",
  "item_id": "c68c9303-9851-476e-96af-aa5bdd385811",
  "message": "The requested item does not exist or has been permanently deleted"
}

For items looked up by producer_id:

{
  "detail": {
    "code": "Items not found",
    "message": "No items were found for the provided producer IDs"
  }
}

Publisher Not Found — 400

{
  "detail": {
    "code": "publisher_not_found",
    "message": "Publisher not found"
  }
}

Publisher / Item Ownership Mismatch — 403

{
  "detail": {
    "code": "item_publisher_mismatch",
    "message": "Item does not belong to the specified publisher"
  }
}

Unauthorized delete attempt:

{
  "detail": {
    "code": "Unauthorized access",
    "message": "You don't have permission to delete these items",
    "unauthorized_items": ["c68c9303-9851-476e-96af-aa5bdd385811"]
  }
}

Vector-Store Update Failure — 502 Returned by the single-item PATCH endpoint when the vector store update fails.

{
  "detail": {
    "code": "Weaviate update failed",
    "message": "Postgres not modified due to vector store update failure",
    "weaviate_error": "Weaviate update failed"
  }
}

Batch / Request Validation — 400 Missing patch operations:

{
  "detail": {
    "code": "Invalid request",
    "message": "At least one patch operation is required"
  }
}

Missing item IDs in a delete request:

{
  "detail": {
    "code": "Invalid request",
    "message": "At least one item_id is required"
  }
}

Missing producer IDs:

{
  "detail": {
    "code": "Invalid request",
    "message": "At least one producer_id must be provided"
  }
}

Search & Recommendations

Search

POST /ai/v1/data/search

Recommendations

POST /ai/v1/data/items/recommendations/base

Invalid Collection — 400

{
  "detail": "Invalid Collection. Please see https://docs.gloo.com/api-guides/search#making-requests for information on providing a valid collection."
}

Missing or Invalid Tenant — 400

{
  "detail": "Unable to search tenant, InvalidTenant, in collection, GlooProd. Please provide a valid tenant. See https://docs.gloo.com/api-guides/search#making-requests for information on providing a valid tenant."
}

For multi-tenant collections where tenant is omitted:

{
  "detail": "Unable to search multi-tenant collection, GlooProd. Please provide a valid tenant. See https://docs.gloo.com/api-guides/search#making-requests for information on providing a valid tenant."
}

Missing Authorization — 401 Returned by the gateway when the Authorization header is missing.

{
  "error": "Missing Authorization",
  "code": "unauthorized_missing_authorization"
}

Invalid Authorization — 403 Returned by the gateway when the Authorization header is present but malformed or the API key is invalid.

{
  "error": "Forbidden - insufficient permissions",
  "code": "forbidden"
}

Validation Errors — returned as 403 Empty query, empty collection, and invalid limit values return HTTP 403 rather than 422. Don’t treat these as permission errors — they indicate an invalid request body. Empty query:

{
  "detail": [
    {
      "type": "string_too_short",
      "loc": ["body", "query"],
      "msg": "String should have at least 1 character",
      "input": ""
    }
  ]
}

Invalid limit:

{
  "detail": [
    {
      "type": "greater_than_equal",
      "loc": ["body", "limit"],
      "msg": "Input should be greater than or equal to 1",
      "input": -1
    }
  ]
}

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.

Error Handling Best Practices

Log error.name and error.code, not just the status — Status codes tell you the category; the symbolic name and numeric code tell you exactly what went wrong. Log them in your error handler for precise alerting and debugging. Use error.retryable for Completions retries — For non-streaming responses, use the HTTP status plus error.retryable. For streaming responses, inspect stream error events and use error.retryable. Some failures happen inside an HTTP 200 stream after headers have been sent. Retry only transient failures — 408 provider timeouts and retryable 5xx failures are candidates for bounded retries. A 429 is not automatically retryable: 1005 / SPENDING_LIMIT_EXCEEDED requires the limit condition to be resolved, while an endpoint-specific quota may provide Retry-After. Use exponential backoff for retries — Wait (2^attempt) + jitter between retries, up to 5 attempts for non-streaming requests. Live streaming needs much lower ceilings — see Handling Streaming Failures for streaming retry budgets and Rate Limits for pseudocode. Use detail to pinpoint validation failures — For 422 responses, the detail array tells you exactly which field failed: loc is the field path, msg is the reason, and input is the value you sent. Open a ticket with the trace_id for persistent inference issues — If inference errors continue after retrying with backoff, contact us at hello@gloo.us and include the trace_id returned in the error response. The trace_id lets us trace the exact request and resolve the issue faster.

​Quick Reference

HTTP Status Codes

Error Code Reference

AI Error Object

Streaming Errors

Authentication Errors

Rate Limiting

Endpoint-Specific Errors

Best Practices

​HTTP Status Codes

​Error Code Reference

​AI Error Object

​Common Error Scenarios

​Authentication Errors

​401 Unauthorized — Missing or Invalid API Key

​403 Forbidden — Insufficient Permissions

​Validation Errors (400 / 422)

​Missing Required Field

​Invalid Routing Configuration

​Invalid Data Type

​Resource Not Found (404)

​Duplicate Upload Results

​Duplicate Content (Ingestion)

​Rate Limiting (429)

​Server Errors (5xx)

​500 Internal Server Error

​502 Bad Gateway

​503 Service Unavailable

​Streaming Errors

​Content Filter During Streaming

​Grounded Streaming Citations

​Endpoint-Specific Errors

​Completions V2

Completions V2 Reference

​Grounded Completions

Grounded Completions Reference

​Ingestion

Ingestion V2 Reference

​Content Controls (Data Engine)

Single Item Patch

Multi-Item Patch

Delete Items

Get Item Metadata

Get Item by Producer ID

​Search & Recommendations

Search

Recommendations

​Error Handling Best Practices

Quick Reference

HTTP Status Codes

Error Code Reference

AI Error Object

Common Error Scenarios

Authentication Errors

401 Unauthorized — Missing or Invalid API Key

403 Forbidden — Insufficient Permissions

Validation Errors (400 / 422)

Missing Required Field

Invalid Routing Configuration

Invalid Data Type

Resource Not Found (404)

Duplicate Upload Results

Duplicate Content (Ingestion)

Rate Limiting (429)

Server Errors (5xx)

500 Internal Server Error

502 Bad Gateway

503 Service Unavailable

Streaming Errors

Content Filter During Streaming

Grounded Streaming Citations

Endpoint-Specific Errors

Completions V2

Grounded Completions

Ingestion

Content Controls (Data Engine)

Search & Recommendations

Error Handling Best Practices