> ## 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/` (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 ` with a live `ak_`/`mk_` key or OAuth token. | | `PAYMENT_REQUIRED` | 402 | A plan limit was reached (agents, identities, monthly volume). | Upgrade the tier or wait for the billing period; see [Pricing & Limits](/pricing-and-limits). | | `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 request the `admin:full` scope in the OAuth flow. | | `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_NOT_VERIFIED` | 409 | The upstream provider (SES sandbox) only delivers to verified recipients. | Verify the recipient at AWS or request SES production access; `details.remediation` explains both. | | `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