---
title: "AI Gateway errors and limits"
canonical_url: "https://www.nutrient.io/guides/dws-ai-gateway/errors/"
md_url: "https://www.nutrient.io/guides/dws-ai-gateway/errors.md"
last_updated: "2026-10-14T00:00:00.000Z"
description: "Handle AI Gateway authentication, quota, rate-limit, and provider errors, and review request limits."
---

# AI Gateway errors and limits

AI Gateway returns OpenAI-compatible errors with an `error` object containing `message`, `type`, `param`, and `code`. Inspect the HTTP status and error code before retrying.

## Error responses

| Status | Meaning                                     | Action                                                                                                                       |
| ------ | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid or unsupported request.             | Check the model, parameters, input types, and error message. Decision API validation can return `upstream_rejected_request`. |
| `401`  | Missing, invalid, or revoked key.           | Check the bearer key and replace revoked credentials.                                                                        |
| `402`  | `insufficient_quota`.                       | Check remaining included usage and pay-as-you-go settings.                                                                   |
| `403`  | Key lacks permission.                       | Confirm AI Gateway access and the key’s product scope.                                                                       |
| `404`  | Unknown model or unavailable feature.       | List available models and confirm account access.                                                                            |
| `413`  | Request or state exceeds a size limit.      | Reduce the JSON body, or the decision API `state` to within the model’s limit.                                               |
| `429`  | Gateway or provider rate limit.             | Honor `Retry-After` when present and reduce concurrency.                                                                     |
| `500`  | Internal error.                             | Retry with bounded backoff; contact support if it persists.                                                                  |
| `502`  | Model provider failure.                     | Retry transient failures with bounded backoff.                                                                               |
| `503`  | Service overloaded or provider unavailable. | Retry later; contact support for persistent failures.                                                                        |
| `504`  | Model request timed out.                    | Reduce the workload and retry cautiously.                                                                                    |

A retry sends a new request and can incur another charge. Do not automatically retry invalid requests, authentication errors, or exhausted quota. Use bounded exponential backoff with jitter for transient failures.

## Request limits

See the [API reference](https://www.nutrient.io/api/reference/ai-gateway/public/) for rate, request size, and input limits. Test keys have separate rate and spend controls. Context and output limits vary by model.

## Streaming failures

After an SSE response starts, errors can arrive within the stream. Handle failure events and missing completion events even if the initial HTTP status was successful. Preserve the request ID for diagnosis.

## Get help

Send the request ID, endpoint, model alias, status, error code, and timestamp with time zone to [support](https://support.nutrient.io/). For decision API requests, include `x-typesafe-request-id`. Do not send API keys or sensitive prompt content. For account enablement or commercial requirements, [contact sales](https://www.nutrient.io/contact-sales/?lob=dws-api).
---

## Related pages

- [DWS AI Gateway API](/guides/dws-ai-gateway.md)
- [Get started with DWS AI Gateway API](/guides/dws-ai-gateway/getting-started.md)
- [AI Gateway pricing](/guides/dws-ai-gateway/pricing.md)
- [AI Gateway security and privacy](/guides/dws-ai-gateway/security-and-privacy.md)
- [Make decisions with the decision API](/guides/dws-ai-gateway/system-one.md)