# Errors

> The one error shape every /v1 endpoint answers with, how its codes are formed, the codes you will meet with what to do about each, OAuth errors and when to retry.

Source: https://docs.dissolve.email/errors

Every `/v1` error has the same shape, whatever went wrong:

```json
{
  "error": {
    "code": "plan_limit_exceeded",
    "message": "You've reached your limit of 10 active inboxes on the pro plan. Upgrade to Business for more.",
    "details": { "limit": 10, "current": 10, "tier": "pro", "upgradeTier": "business", "upgradeCta": true }
  }
}
```

| Field | What it is |
|---|---|
| `code` | A stable lower-case code to branch on. It never changes for a given error. |
| `message` | A sentence for a person, safe to show as it is. It may be reworded; do not parse it. |
| `details` | Optional. Whatever else the error knows: the limit and usage, the invalid fields, the scope that was missing, when to try again. |

Every answer, error or not, carries an `X-Request-Id` header. Quote it when you write to [support](/support).

## How codes are formed

`/v1` runs the same handlers as the app, then puts their errors in this envelope. When a handler names its error (`PLAN_LIMIT_EXCEEDED`), the code is that name in lower case (`plan_limit_exceeded`). When it does not, the code comes from the HTTP status:

| Status | Code |
|---|---|
| 400, 422 | `invalid_request` |
| 401 | `unauthorized` |
| 402 | `payment_required` |
| 403 | `forbidden` |
| 404 | `not_found` |
| 409 | `conflict` |
| 410 | `gone` |
| 413 | `too_large` |
| 429 | `rate_limited` |
| 500 and up | `server_error` |

Any other fields the handler sent move into `details`. Branch on the status first and the code second.

## Codes you will meet

### Credentials and scopes

| Status | Code | Means |
|---|---|---|
| 401 | `unauthorized` | No `Authorization: Bearer` header, or a token of an unknown kind |
| 401 | `invalid_api_key` | The API key is wrong or was revoked |
| 401 | `invalid_token` | The OAuth access token expired, was revoked, or its connection was removed |
| 403 | `plan_required` | API keys need Pro or Business; connect through OAuth on Free |
| 403 | `insufficient_scope` | The connection lacks the scope in `details.scope`; `WWW-Authenticate` names it too |

[Authentication](/authentication#when-a-credential-is-refused) says what to do about each.

### Requests

| Status | Code | Means |
|---|---|---|
| 400 | `validation_error` | The body broke a rule. `details.fields` lists each field with its `field`, `message` and `code` |
| 400 | `invalid_name`, `invalid_alias`, `invalid_domain`, `invalid_pattern` | A name, alias, domain or rule pattern is not allowed; `message` says why |
| 400 | `invalid_forward_target` | Forwarding to a dissolve.email address or a known disposable service is refused |
| 400 | `invalid_webhook_url` | The webhook address is not public https (`details.reason` says why) |
| 404 | `not_found` | No such thing, or it is not yours. A message, inbox or label you cannot see answers the same as one that does not exist |
| 404 | `not_found` | No such `/v1` endpoint |
| 409 | `name_taken`, `alias_taken`, `conflict` | The address is in use, reserved or held back, or the thing already exists |
| 410 | `gone` | The inbox has expired (an identity's says `inbox_expired`) |

### Plans and ownership

| Status | Code | Means |
|---|---|---|
| 403 | `upgrade_required` | The feature needs a higher plan (`details.requiredPlan` when known): custom names, forwarding, aliases, search, webhooks, rules, labels |
| 403 | `forbidden` | Agent identities, personas or the vault need Pro or Business. An attachment download on Free is also `forbidden`, with `details.code` `PLAN_REQUIRED` |
| 403 | `owner_only` | You are a team member: you can read a shared inbox but only its owner can delete, extend, forward or alias it |
| 403 | `plan_limit_exceeded` | As many active inboxes as the plan allows |
| 403 | `extension_limit_reached` | Free inboxes can be extended once |
| 403 | `lifetime_limit_reached` | The inbox has reached the longest life the plan allows; make a new one |
| 403 | `alias_limit_reached`, `reservation_limit` | The plan's aliases per inbox or reserved names are used up |
| 400 or 429 | `rule_limit`, `label_limit`, `webhook_limit`, `template_limit`, `limit_exceeded` | A count limit of the plan; delete one first |

### Rates and timing

| Status | Code | Means |
|---|---|---|
| 429 | `rate_limited` | The credential's per-minute rate is used up. `Retry-After: 60` |
| 429 | `too_many_waits` | Five waits are already open for this credential. `Retry-After: 5` |
| 429 | `resource_limit_exceeded` | An hourly cap, or polling the message list too often. `details.resetAt` says when |
| 429 | `hourly_limit_exceeded` | Free accounts make five inboxes an hour |
| 429 | `extend_too_early` | Pro and Business inboxes can be extended only near the end. `details.availableAt` says when |

[Rate limits and plans](/rate-limits) has the figures behind each.

### Our side

| Status | Code | Means |
|---|---|---|
| 500 | `server_error` | Something broke on our side. `details.requestId` matches `X-Request-Id` |
| 503 | `MAINTENANCE` | A short maintenance window. This one answer is not in the envelope: it is `{ "error": "MAINTENANCE", "message", "until" }` with `Retry-After: 60` |

## OAuth endpoints

`/oauth/register`, `/oauth/authorize` and `/oauth/token` answer the way OAuth 2.1 specifies, not with the envelope above:

```json
{ "error": "invalid_grant", "error_description": "The refresh token has expired. Connect again." }
```

| `error` | From | Means |
|---|---|---|
| `invalid_request` | authorize, token | A required parameter is missing, or PKCE `S256` was not used |
| `invalid_client` | authorize, token, revoke | Unknown or disabled client, or wrong client authentication |
| `invalid_client_metadata`, `invalid_redirect_uri` | register | The registration was refused; the description says why |
| `invalid_grant` | token | The code or refresh token is wrong, expired, already used or its connection removed |
| `invalid_scope` | authorize | No requested scope is known or allowed for this client |
| `invalid_target` | authorize | `resource` is not one this server serves |
| `unsupported_grant_type`, `unsupported_response_type` | token, authorize | Only `authorization_code`, `refresh_token` and `response_type=code` exist |
| `access_denied` | authorize redirect | The person declined |
| `slow_down` | register, authorize, token | Too many requests from your address |
| `temporarily_unavailable` | all | OAuth is switched off on this server |

Once the client and redirect address are known good, authorize errors come back to your redirect address as `error`, `error_description`, `state` and `iss`; before that they are shown as JSON.

## When to retry

- **Retry** `429` after `Retry-After`, `503` after `Retry-After`, and `500`, `502` or `504` on a read or a delete, with backoff. The [TypeScript SDK](/sdk) does this for you.
- **Do not retry** `400`, `401`, `403`, `404`, `409` or `410` unchanged: the same request gets the same answer. Fix the request, refresh the token or change the plan first.
- **Be careful with creates.** A `POST` that timed out may have worked: list before you create again, or you may hold two inboxes.
- A wait that answers `found: false` is not an error: nothing arrived in time. Call it again.
