# Errors

> Every error ACOG itself returns, with its HTTP status, type, extra fields, cause and what to do. Errors from your provider are passed through unchanged.

Product: AI Cost Optimizer Gateway (ACOG). Web version: https://tessarac.com/docs/acog/reference/errors. Last updated: 2026-10-16.

Errors ACOG returns itself use this envelope:

```json
{ "error": { "type": "model_not_configured", "message": "…" } }
```

Some types add fields, listed below. An error from your provider is passed through with its own status and body, unless ACOG maps it to one of the types below. On native routes, provider errors are always passed through unchanged. Failed responses are never cached.

## Authentication and authorization

| Status | `type` | Cause | What to do |
|---|---|---|---|
| 401 | `unauthorized` | No gateway key found, or the key is unknown, disabled, expired, or used from outside its IP allowlist | Check the key and the header it is in ([Base URLs and authentication](https://tessarac.com/docs/acog/api/base-urls-and-authentication.md#authentication)) |
| 403 | `forbidden` | The key lacks the gateway access scope (`proxy`); or, on `/bedrock`, the request signature does not verify | Use a key with `proxy`; for Bedrock, use an issued ACOG credential and a correct clock |
| 503 | `service_unavailable` | ACOG could not reach its key or configuration store | Retry |

## Governance

| Status | `type` | Extra fields | Cause |
|---|---|---|---|
| 402 | `budget_exhausted` | `scope` (`org`, `group`, `user`), `window` (`day`, `week`, `month`), `decision_id` | A budget is used up. See [Budgets](https://tessarac.com/docs/acog/govern/budgets.md). |
| 429 | `rate_limited` | `Retry-After` header | A rate limit is reached. See [Rate limits](https://tessarac.com/docs/acog/govern/rate-limits.md). |
| 403 | `model_not_allowed` | `scope` (`org`, `team`, `user`, `service-key`) | A model access rule refuses the model. See [Model access](https://tessarac.com/docs/acog/govern/model-access.md). |
| 403 | `model_unverifiable` | `channel` | A native-route request whose model cannot be determined, while a model access rule applies |
| 403 | `dlp_blocked` | `category`, `reason`, `decision_id` | Data loss prevention blocked the request. See [Data loss prevention](https://tessarac.com/docs/acog/govern/data-loss-prevention.md). |
| 400 | `prompt_injection_blocked` | `category` | Prompt injection screening blocked the request. See [Prompt injection protection](https://tessarac.com/docs/acog/govern/prompt-injection.md). |

## Routing and the request

| Status | `type` | Cause | What to do |
|---|---|---|---|
| 409 | `model_not_configured` | No connection declares the model; `auto` with no connections; an `x-acog-channel` value with no matching connection; or no `model` in the body | Declare the model on a connection under **Admin → Providers** |
| 409 | `connection_not_configured` | A native route with no connection for that provider, or a connection missing a required setting | Create or complete the connection |
| 409 | `connection_not_usable` | The connection's address, port or region is not allowed on the hosted service | Edit the connection ([Connecting providers](https://tessarac.com/docs/acog/providers/overview.md#hosted-service-what-acog-can-reach)) |
| 400 | `invalid_request_error` | The body is not valid for the endpoint, a referenced image could not be fetched, or a native path contains `.` or `..` segments | Fix the request |
| 413 | `request_too_large` | The body is over 64 MiB | Send less, or reference large files by URL |
| 413 | `context_window_exceeded` | The prompt is larger than the model's context window. Extra fields: `model`, `context_window`, `estimated_tokens`. | Shorten the prompt or use a model with a larger window |
| 422 | `translation_unsupported` | A field cannot be translated faithfully to the serving model's API | Remove the field, or call a model that speaks the same API |
| 422 | `embeddings_unsupported_shape` | No connection that declares the model can serve embeddings | Declare the model on an OpenAI, Azure OpenAI or compatible connection |

## Your provider

| Status | `type` | Extra fields | Cause | What to do |
|---|---|---|---|---|
| 422 | `model_access_required` | `provider_status`, `provider_detail` | Your provider account cannot use the model (Bedrock model access, Vertex Model Garden, Azure deployment) | Enable the model in your provider account; the message says how |
| 422 | `upstream_auth_failed` | `provider_status`, `provider_detail` | Your provider rejected the connection's stored key | Update the key under **Admin → Providers** |
| 502 | `upstream_auth_error` | | ACOG could not obtain a credential for the provider, for example a keyless exchange was refused | See the provider's troubleshooting section ([Keyless connections](https://tessarac.com/docs/acog/providers/keyless-connections.md#troubleshooting)) |
| 500 | `credentials_error` | | A stored credential could not be used | Contact your administrator; re-enter the connection's credentials |
| 502 | `upstream_error` | | A network or protocol failure reaching the provider | Retry |
| 503 | `upstream_unavailable` | `Retry-After: 5` | The provider's platform is failing repeatedly and ACOG is pausing requests to it | Retry after the delay |

## Batches

| Status | `type` | Cause |
|---|---|---|
| 404 | `batch_not_found` | No such batch job for your organization |
| 502 | `batch_failed` | The provider's batch job failed. Extra fields: `id`, `status`. |
| 502 | `batch_poll_failed`, `batch_connection_unavailable` | ACOG could not check the job, or the job's connection no longer exists |

## Hosted service: errors from the edge

These apply only to the console's address, `acog.tessarac.com/gateway`, which goes through the edge network in front of the console. There, a request that sends nothing back for 60 seconds is closed with `504`, and some `403`, `404` and `5xx` responses arrive as an HTML page from the edge rather than the JSON envelope above. `gateway.acog.tessarac.com` has no edge in front of it; use it, and see [Base URLs](https://tessarac.com/docs/acog/api/base-urls-and-authentication.md#base-urls).