# Errors

> Every error the DigitSpace gateway returns, with its status, type and code, what causes it and what to do, plus which errors are worth retrying.

Source: https://digitspace.ai/docs/reference/errors · Last checked: 2026-10-31

## Shape

On `/v1/chat/completions`, `/v1/models` and `/v1/key`, errors use OpenAI's shape:

```json
{
  "error": {
    "message": "This API key's budget is used up.",
    "type": "budget_exceeded",
    "code": "budget_exceeded"
  }
}
```

On `/v1/messages`, they use Anthropic's shape, without `code`:

```json
{
  "type": "error",
  "error": {
    "type": "budget_exceeded",
    "message": "This API key's budget is used up."
  }
}
```

`message` is written for people and may change; match on `type` and `code` in code.

## Every error

| Status | `type` | `code` | When | What to do |
| --- | --- | --- | --- | --- |
| 401 | `authentication_error` | none | The key is missing, wrong, disabled, deleted or expired, or is a master key. | Send a live API key as `Authorization: Bearer <key>` or `x-api-key`. |
| 403 | `permission_error` | none | The key's project or organisation isn't active, or the caller's IP isn't on the key's allow list. | Check the project in the dashboard, or the key's IP rules. |
| 413 | `invalid_request_error` | none | The body is over the size limit (20 MB). | Send smaller images or files, or fewer of them. |
| 400 | `invalid_request_error` | none | The body isn't JSON, `model` or `messages` is missing, or `max_tokens` is missing on /v1/messages. | Fix the request body; the message names the field. |
| 400 | `invalid_request_error` | `content_blocked` | A guardrail blocked the request. | Change the content, or the guardrail rule in the dashboard. |
| 404 | `not_found_error` | `model_not_found` | No model has that ID or alias. | List models with `GET /v1/models`. |
| 400 | `invalid_request_error` | `capability_mismatch` | No provider of the model can do what the request needs (tools, images, JSON schema, reasoning, streaming or context size). | Choose another model, or `auto`. |
| 403 | `permission_error` | `model_not_allowed` | The key's or organisation's rules don't allow the model or provider. | Use an allowed model, or change the rules. |
| 403 | `permission_error` | `devpass_provider_pinned` | A DevPass key asked for `provider/model`. | Send the model ID alone; DevPass chooses the provider. |
| 402 | `insufficient_quota` | `devpass_inactive` | The DevPass key's organisation has no active pass. | Start or renew the pass. |
| 402 | `insufficient_quota` | `devpass_paused` | The pass is paused. | Contact support. |
| 402 | `insufficient_quota` | `devpass_monthly_limit` | The pass's monthly allowance is used up. | Wait for the time in `Retry-After`, or upgrade. |
| 402 | `insufficient_quota` | `devpass_daily_limit` | Today's share of the allowance is used up. | Wait for the time in `Retry-After`. |
| 402 | `insufficient_quota` | `devpass_premium_limit` | This week's premium-model share is used up. | Use a non-premium model or `auto`, or wait for `Retry-After`. |
| 429 | `rate_limit_error` | `devpass_concurrency` | The DevPass key already has its maximum requests in flight. | Wait for a request to finish. |
| 429 | `rate_limit_error` | `rate_limited` | Your organisation passed its requests per minute, or a per-minute or per-day rule on a model or provider. | Slow down and retry after a short wait. |
| 429 | `spend_cap_reached` | `daily_cap` | Your organisation reached its daily spend cap for its tier. | Wait until tomorrow (UTC), or ask support to raise it. |
| 429 | `spend_cap_reached` | `monthly_cap` | Your organisation reached its monthly spend cap for its tier. | Wait for next month, or ask support to raise it. |
| 429 | `budget_exceeded` | `budget_exceeded` | A budget on the key, member or team is used up. | Raise the budget in the dashboard, or wait for it to reset. |
| 402 | `insufficient_credits` | `insufficient_credits` | The request runs on credits and the balance is too low. | Top up, or add your own provider key. |
| 503 | `api_error` | `no_provider_available` | The model exists but no provider can take the request right now. | Retry shortly, or choose another model. |
| 502 | `api_error` | `provider_failed` | Every provider tried for the request failed. | Retry shortly. |
| 500 | `api_error` | none | Something failed inside the gateway. | Retry; if it continues, contact support with the `x-request-id`. |

## Errors from providers

When a provider turns a request down with a `4xx` other than `429`, the gateway returns the provider's status with `type` `invalid_request_error` and the message "The provider rejected the request: …", followed by the provider's own explanation. It doesn't try another provider, because the request itself is the problem. Fix the request, or try another model.

## What to retry

| Status                                                                     | Retry?                                                                                   |
| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `429 rate_limit_error`                                                     | Yes, after a short wait that grows with each attempt (for example 1, 2, then 4 seconds). |
| `402` DevPass limits                                                       | After the `Retry-After` header's seconds.                                                |
| `502`, `503`, `500`                                                        | Yes, a few times with growing waits. The gateway has already tried other providers.      |
| `429 budget_exceeded`, `429 spend_cap_reached`, `402 insufficient_credits` | Not until the budget, cap or balance changes.                                            |
| `400`, `401`, `403`, `404`, `413`                                          | No. Fix the request, key or rules first.                                                 |

Only DevPass limit errors carry `Retry-After`. Other `429`s don't, so choose your own wait.