> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useanima.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# API Error Reference

> Every error code the Anima API emits — RFC 7807 problem types, what they mean, and how to fix them.

# API Errors

The Anima API returns errors as [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807) `application/problem+json`. The `type` URI is always `https://docs.useanima.sh/errors/<code>` (the code, lowercased, `_` → `-`) — those URIs are stable forever, and they all resolve to this page. Machine clients should branch on the `code` extension field.

```json theme={null}
{
  "type": "https://docs.useanima.sh/errors/rate-limited",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Too many requests",
  "instance": "/v1/email/send",
  "code": "RATE_LIMITED",
  "details": { "retryAfter": 12 },
  "error": { "code": "RATE_LIMITED", "message": "Too many requests" }
}
```

* `code` and `details` are Anima extensions (RFC 7807 permits extensions).
* Many errors include `details.remediation` — a `hint` written for both humans and LLM agents, sometimes with a `docsUrl` or `verificationUrl`. Agents should surface or act on the hint before retrying.
* The legacy `error: { code, message, details }` sibling is preserved through SDK v1.x and will be removed in v2.
* Every response carries `x-request-id` (unique per call) and `x-correlation-id` (stable per workflow) — include both when contacting support.

## Request errors (4xx)

| Code | HTTP | Meaning | What to do |
| - | - | - | - |
| `VALIDATION_ERROR` | 400 | The request body or parameters failed schema validation. | Fix the request shape; `details` carries field-level errors. |
| `BAD_REQUEST` | 400 | The request is well-formed but invalid in the current state (e.g. re-enabling an already-active webhook, replaying a delivery that isn't dead-lettered). | Read `detail` — it names the state that blocked the operation. |
| `INVALID_IDEMPOTENCY_KEY` | 400 | `Idempotency-Key` isn't 1–255 printable ASCII characters. | Send a UUID (or any conforming string). |
| `UNAUTHORIZED` | 401 | Missing or invalid credentials. | Send `Authorization: Bearer <key>` with a live `ak_`/`mk_` key or OAuth token. |
| `PAYMENT_REQUIRED` | 402 | A plan limit was reached (agents, identities, monthly volume), **or** outbound voice used up its included minutes and the authorized overage. On the voice case `details` carries `resource: "voice"` with `includedCredits`, `usedCredits`, `overageUsedCents` and `overageCapCents`. | Upgrade the tier, wait for the billing period, or enable [metered overage](/pricing-and-limits#metered-overage) and raise the limit. |
| `VOICE_MONTHLY_CAP_EXCEEDED` | 402 | The tier's monthly outbound-call cap is used up. | Upgrade or wait until the next billing period; `details` carries `current`/`cap`. |
| `FORBIDDEN` | 403 | Authenticated, but not allowed: acting on another agent's resources, or an [agent capability policy](/security#agent-capability-policies) refused the action. | Use the right key for the agent, or have an org admin adjust the agent's policy. |
| `MASTER_KEY_REQUIRED` | 403 | The operation needs org-admin authority (agent creation, billing, policy writes). | Use an `mk_` key or the `admin:full` OAuth scope; on the CLI, just run the command — it steps up on its own. For every route, see [Reaching master authority](/security#reaching-master-authority). |
| `NOT_FOUND` | 404 | The resource doesn't exist — or belongs to another organization (deliberately indistinguishable). | Check the id and which org your key belongs to. |
| `CONFLICT` | 409 | State conflict, e.g. a duplicate slug or an already-existing resource. | Change the conflicting value or reuse the existing resource. |
| `IDEMPOTENCY_BODY_MISMATCH` | 409 | The same `Idempotency-Key` was reused with a different body or path. | Use a fresh key per distinct request; reuse keys only for identical retries. |
| `IDENTITY_NOT_VERIFIED` | 409 | The sending email identity isn't verified in the send region. | Follow `details.remediation` — verify the identity or attach one on a verified domain ([Custom Domains](/custom-domains)). |
| `DOMAIN_NOT_VERIFIED` | 409 | Provision-time gate: the email domain isn't added/verified for this workspace. | Add and verify the domain first — see [Custom Domains](/custom-domains). |
| `RECIPIENT_SUPPRESSED` | 409 | The recipient unsubscribed, hard-bounced, or complained — Anima refuses to send to them. | Remove the address from the recipient list; suppressions are inspectable per workspace. |
| `RATE_LIMITED`, `RATE_LIMIT` | 429 | Per-minute/per-hour quota exceeded for the channel. | Honor `Retry-After` and the `X-RateLimit-*` headers; back off and retry. |
| `RATE_LIMIT_PER_SECOND` | 429 | The per-org per-second soft cap was hit. | Smooth the burst; caps scale with tier. |
| `VOICE_RATE_LIMIT_EXCEEDED` | 429 | Outbound dialing exceeded the per-second call cap. | Slow the dialing loop; `details` carries `current`/`cap`. |
| `TCPA_GATE_BLOCKED` | 451 | Outbound calling is blocked until the org completes consent attestation (TCPA/DNC), or this call failed the gate. | Complete the consent attestation in the console; `details.missingFields` lists what's missing. |

## Server errors (5xx)

| Code | HTTP | Meaning | What to do |
| - | - | - | - |
| `INTERNAL_ERROR`, `INTERNAL` | 500 | Unexpected server failure. | Retry with backoff; if it persists, contact support with the `x-request-id`. |
| `BAD_GATEWAY` | 502 | The upstream email provider rejected or failed the request. | Retry; if persistent, the `detail` names the provider error. |
| `PHONE_PROVIDER_ERROR` | 502 | The upstream phone/voice provider failed the operation. | Retry; `detail` names the provider and operation. |
| `SERVICE_UNAVAILABLE` | 503 | The feature is disabled or its infrastructure isn't configured for this environment. | Nothing client-side — the `detail` names the service; contact support if unexpected. |

## Related

* [Webhooks](/webhooks) — delivery signing and retry behavior
* [Security](/security) — key types and agent capability policies
* [Pricing & Limits](/pricing-and-limits) — tier quotas behind 402/429


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.