API Errors

The Anima API returns errors as RFC 7807 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.

{
  "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 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 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.
`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).
`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.
`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.

Webhooks — delivery signing and retry behavior
Security — key types and agent capability policies
Pricing & Limits — tier quotas behind 402/429

Getting Started

Framework Toolkits

Platform

Agent Identity & A2A

Security

Compliance

Protocols

SDK Reference

Resources

Legal

Blog

API Error Reference

API Errors

Request errors (4xx)

Server errors (5xx)

​API Errors

​Request errors (4xx)

​Server errors (5xx)

​Related

API Errors

Request errors (4xx)

Server errors (5xx)

Related