Errors - Gloo

When interacting with the Gloo AI API, handle errors by checking the HTTP status code and then parsing the code or detail field in the response body for precise identification.

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.

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	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.
`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`).
`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.
`PROVIDER_TIMEOUT`	408	Model provider did not respond in time.	Retry with exponential backoff; consider a different model or routing mode if persistent.
`PROVIDER_CONTENT_FILTER`	422	Provider moderated the response.	Adjust the request or user-facing workflow; do not retry unchanged.
`too_many_requests`	429	Request rate limit exceeded.	Wait for the `X-RateLimit-Reset` header value; implement exponential backoff. See Rate Limits.
`SPENDING_LIMIT_EXCEEDED`	429	Spending limit reached for your plan.	Check billing limits; retry only after the limit condition is resolved.
`PROVIDER_INFERENCE_ERROR`	500	Unexpected model inference failure.	Retry with exponential backoff and log `trace_id` if present in the response.
`PROVIDER_UNAVAILABLE`	503	Provider or backing service unavailable.	Retry with exponential backoff.

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": "SPENDING_LIMIT_EXCEEDED",
    "fault": "client",
    "retryable": true,
    "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 429 and 5xx responses. Do not retry 4xx errors (except 429) — 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": "provider_error",
    "code": "PROVIDER_INFERENCE_ERROR",
    "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": "PROVIDER_UNAVAILABLE",
    "fault": "provider",
    "retryable": true,
    "trace_id": "trace-id"
  }
}

Endpoint-Specific Errors

Completions V2

Completions V2 Reference

POST /ai/v2/chat/completions

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": "INVALID_REQUEST",
    "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": "CONTEXT_LENGTH_EXCEEDED",
    "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": "provider_timeout_error",
    "code": "PROVIDER_TIMEOUT",
    "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": "PROVIDER_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": "provider_error",
    "code": "PROVIDER_INFERENCE_ERROR",
    "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": "PROVIDER_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. 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 the code field, not just the status — Status codes tell you the category; the code field tells you exactly what went wrong. Log it in your error handler for precise alerting and debugging. Only retry 429 and 5xx responses — 4xx errors (except 429) mean your request has a problem that won’t go away on retry. Retrying them wastes quota and delays surfacing the real issue. 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.

General

Models

Completions

Content

Data Engine Content Controls

Legacy / Deprecated APIs

Documentation Index

​Quick Reference

HTTP Status Codes

Error Code Reference

Authentication Errors

Rate Limiting

Endpoint-Specific Errors

Best Practices

​HTTP Status Codes

​Error Code Reference

​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

​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

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

Endpoint-Specific Errors

Completions V2

Grounded Completions

Ingestion

Content Controls (Data Engine)

Search & Recommendations

Error Handling Best Practices