Skip to main content

​
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)

CodeHTTPMeaningWhat to do
VALIDATION_ERROR400The request body or parameters failed schema validation.Fix the request shape; details carries field-level errors.
BAD_REQUEST400The 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_KEY400Idempotency-Key isn’t 1–255 printable ASCII characters.Send a UUID (or any conforming string).
UNAUTHORIZED401Missing or invalid credentials.Send Authorization: Bearer <key> with a live ak_/mk_ key or OAuth token.
PAYMENT_REQUIRED402A plan limit was reached (agents, identities, monthly volume).Upgrade the tier or wait for the billing period; see Pricing & Limits.
VOICE_MONTHLY_CAP_EXCEEDED402The tier’s monthly outbound-call cap is used up.Upgrade or wait until the next billing period; details carries current/cap.
FORBIDDEN403Authenticated, 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_REQUIRED403The 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_FOUND404The resource doesn’t exist — or belongs to another organization (deliberately indistinguishable).Check the id and which org your key belongs to.
CONFLICT409State conflict, e.g. a duplicate slug or an already-existing resource.Change the conflicting value or reuse the existing resource.
IDEMPOTENCY_BODY_MISMATCH409The 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_VERIFIED409The 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_VERIFIED409Provision-time gate: the email domain isn’t added/verified for this workspace.Add and verify the domain first — see Custom Domains.
RECIPIENT_NOT_VERIFIED409The upstream provider (SES sandbox) only delivers to verified recipients.Verify the recipient at AWS or request SES production access; details.remediation explains both.
RECIPIENT_SUPPRESSED409The 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_LIMIT429Per-minute/per-hour quota exceeded for the channel.Honor Retry-After and the X-RateLimit-* headers; back off and retry.
RATE_LIMIT_PER_SECOND429The per-org per-second soft cap was hit.Smooth the burst; caps scale with tier.
VOICE_RATE_LIMIT_EXCEEDED429Outbound dialing exceeded the per-second call cap.Slow the dialing loop; details carries current/cap.
TCPA_GATE_BLOCKED451Outbound 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)

CodeHTTPMeaningWhat to do
INTERNAL_ERROR, INTERNAL500Unexpected server failure.Retry with backoff; if it persists, contact support with the x-request-id.
BAD_GATEWAY502The upstream email provider rejected or failed the request.Retry; if persistent, the detail names the provider error.
PHONE_PROVIDER_ERROR502The upstream phone/voice provider failed the operation.Retry; detail names the provider and operation.
SERVICE_UNAVAILABLE503The feature is disabled or its infrastructure isn’t configured for this environment.Nothing client-side — the detail names the service; contact support if unexpected.