# Errors

> Every error code, its HTTP status, what it means and what to do next.

Errors are always JSON, with the same shape everywhere:

```json
{ "error": { "code": "forbidden", "message": "Only an owner can refund a live payment. This key has Limited access: ask a person to do it in the console, or to give the key full access.", "details": { "reason": "owner_only", "console_url": "https://thelastapi.dev/projects/prj_…/payments", "key_url": "https://thelastapi.dev/keys?key=key_…", "next_step": "Tell the user: the account owner does this in the console ▸ the project ▸ Payments ▸ the payment ▸ Refund (or with a full-access key). Retrying with this key will not work. Give the user this link, it opens the place to do it: https://thelastapi.dev/projects/prj_…/payments This key has Limited access. To let it do this from now on, the owner can give it full access in the console: https://thelastapi.dev/keys?key=key_… , or sign in again (vibiz login, or reconnect the MCP server) and choose Full access." } } }
```

- `code` is stable: branch on it, never on `message`.
- `message` says what failed and why, in words to show a person as they are: `Country: “SP” isn't a country code. Spain is ES.`, never a bare "something went wrong" when the reason is known.
- `details.reason` refines a code (`owner_only`, `payouts_not_ready`, `daily_spend`…).
- `details.next_step`, when present, is what to tell the person. Agents pass it on instead of retrying.
- `details.console_url`, when present, is the console page where it is fixed.
- Every response has an `X-Request-Id`; quote it to support.
- AI routes add OpenAI's `type` and `param` so OpenAI SDKs read them.

## Codes

| Code | Status | Meaning | Next step |
| --- | --- | --- | --- |
| `invalid_request` | 400 | The request is malformed or a field is wrong. `details` names the field (`issues[].path`, `param`, `problems`) | Fix the field; don't retry unchanged |
| `content_filtered` | 400 | An AI content filter refused the request | Change the input |
| `context_length_exceeded` | 400 | The AI input is longer than the model's window | Shorten it or use a larger model |
| `unauthorized` | 401 | Missing, unknown or revoked key; an app key on an account route | Check the key and its kind |
| `forbidden` | 403 | Not allowed for this key. With `reason: owner_only`: the key is Limited without `details.permission` | Give the person `details.grant_url` (allows that permission for this key, or everything) or `details.console_url` (do it themselves); retry once allowed |
| `no_account` | 403 | Signed in to the console with no account yet | Create an account or link a key in the console |
| `not_found` | 404 | No such object on this account or in this environment | Check the id and `env` |
| `conflict` | 409 | The object's state doesn't allow it (`details.reason` says why), or a concurrent request with the same `Idempotency-Key` is still running | Read the object again; act on `reason` |
| `domain_taken` | 409 | The slug or domain belongs to someone else | Pick another |
| `dependency_not_ready` | 409 | A resource this needs is missing or still provisioning | Add it or wait, then retry |
| `insufficient_balance` | 409 | The project's balance can't cover a refund | Wait for more sales, or refund less |
| `payment_required` | 402 | The account is out of credits for a paid call (`details.reason`: `insufficient_balance`, or `past_due` for deploys after a week at zero) | Pass `details.next_step` and `top_up_url` to the person; don't retry until credits are added |
| `quota_exceeded` | 413 | A stored quota is full (replay) | Delete or wait for retention |
| `payload_too_large` | 413 | The body or upload is over its cap | Send less |
| `idempotency_mismatch` | 422 | The same `Idempotency-Key` was used with a different body | Use a new key for a new request |
| `rate_limited` | 429 | A limit was reached; `details` says which and `resets_at` | Wait (`Retry-After` or `resets_at`); don't loop |
| `client_outdated` | 426 | The thelastapi CLI that called is older than the API supports; `details.minimum` | Update it: `npm install -g @vibiz/cli@latest`, then retry |
| `internal` | 500 | Our bug | Retry once; then contact support with `X-Request-Id` |
| `provider_failed` | 502 | The work was refused downstream (a refund refused; your own AI key rejected); `message` says why and `details.refused_because` carries the service's own reason when it gave one | Act on the reason; retrying unchanged rarely helps |
| `provider_unavailable` | 503 | The service is unavailable right now, or the call timed out (`details.reason`) | Retry later with backoff |
| `model_unavailable` | 503 | No route can run the model you asked for right now. thelastapi never swaps in another model | Retry after `details.retry_after_seconds`, or pick another model |
| `not_configured` | 503 | This deployment doesn't offer that capability now | Use another model or capability |

## Fields

A `400 invalid_request` names every field that is wrong, and the rule it broke, in its `message` (`name: must have at most 80 characters.`, or `3 fields need fixing: …` for several). `details` carries the same for forms:

```json
{ "error": { "code": "invalid_request", "message": "Country: “SP” isn't a country code. Spain is ES.", "details": { "field": "contact.country", "fields": ["contact.country"], "problems": [{ "field": "contact.country", "message": "Country: “SP” isn't a country code. Spain is ES." }], "issues": [{ "path": "contact.country", "message": "“SP” isn't a country code. Spain is ES." }] } } }
```

- `field` is the first field (a dotted path into the body, or the query parameter), `fields` all of them.
- `problems[]` is `{ field, message }`, the message naming the field: show each under its field.
- `issues[]` is `{ path, message }` without the field's name, for older clients.

## When a service refuses

When a service thelastapi works with refuses something on its merits (a name a registry won't take, a value it rejects), the error says what it said, in its own words but never its name, links or ids: `provider_failed` with `The request was refused: <reason>.` and the reason alone in `details.refused_because`. Where the reason is about one of your fields, the error is `invalid_request` with that field instead. With no reason given, the message says so: write to support@vibiz.ai with the `X-Request-Id`.

## Retries and idempotency

Any `POST` accepts `Idempotency-Key`. The first successful JSON response is stored for 24 hours and replayed for a retry with the same body, so a retried payment checkout, email or AI call can't happen twice. A different body under the same key is `idempotency_mismatch`; a concurrent request with the same key while the first is running is `conflict`. Streams and audio aren't replayed. Server errors aren't stored, so they can be retried.

Retry `429` (after the reset), `502`/`503` and network errors with backoff. Never retry `400`, `401`, `403` or `409` unchanged.

## In the MCP server

Tool errors are `isError: true` results whose text is the same JSON. A failed build waited on by `vibiz_deploy` comes back as `deployment_failed`.
