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

429 responses and how to implement retry logic with exponential backoff.

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	Valid token but caller lacks permission 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`	Rate Limited	Exceeded request rate or spending limit for your plan. Retry after `X-RateLimit-Reset`.
`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 <token>` to all requests.
`forbidden`	403	Valid token but caller lacks permission for the resource or publisher.	Verify `publisher_id` belongs to your org; check API credential scopes.
`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	Spending limit reached for your plan.	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 exponential backoff.
`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 platform error.	Retry only if `error.retryable` is `true`; 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.
`too_many_requests`	429	Request rate limit exceeded.	Wait for the `X-RateLimit-Reset` header value; implement exponential backoff. See Rate Limits.

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.

Common Error Scenarios

Authentication Errors

These errors occur when there is an issue with your bearer token or the permissions associated with your API credentials.

401 Unauthorized — Missing or Invalid Token

Returned when the Authorization header is missing from the request.

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

For Completions and Search endpoints, an invalid or expired token returns:

{
  "detail": "Invalid or expired access token."
}

403 Forbidden — Insufficient Permissions

Returned when your token is valid, but the caller does not have permission for the requested resource or publisher.

{
  "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)

Returned when you exceed the request rate limit for your plan.

{
  "error": "Rate limit exceeded",
  "code": "too_many_requests"
}

For Completions endpoints, a spending limit response includes additional error detail:

{
  "detail": {
    "message": "Spending limit reached",
    "code": "SPENDING_LIMIT_EXCEEDED"
  },
  "error": {
    "message": "Spending limit reached",
    "type": "rate_limit_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"
  }
}

Rate limit response headers:

Header	Description
`X-RateLimit-Limit`	Total requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

See Rate Limits for exponential backoff pseudocode examples.

Server Errors (5xx)

Only retry 408, 429, and 5xx responses. Do not retry other 4xx errors — they indicate a request problem that won’t resolve on retry.

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.

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 or Invalid Authorization — 401 This endpoint does not return a specific error code for 401 responses. Ensure your JWT includes a sub claim (Client ID) and scope: api/access. 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/data/v1/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."
}

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. Only retry non-streaming 408, 429, and 5xx responses by default — 408 provider timeouts are safe to retry with backoff. Other 4xx errors, except 429, mean your request has a problem that won’t go away on retry. Use exponential backoff for retries — Wait (2^attempt) + jitter between retries, up to 5 attempts. See 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.

Documentation Index

​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 Token

​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 Token

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