Error catalogue
71 codes. Every 4xx and 5xx carries code, message, fix and docs_url, and either a wait hint or none at all: a refusal that waiting cannot cure never carries retry_after_seconds.
Every code
validation_error400 · not retryable
Error in one or more fields.
Fix Correct the fields listed in the error details and retry the request.
https://agentisend.com/docs/errors#validation_error
invalid_idempotency_key400 · not retryable
Idempotency-Key must be 1-256 characters.
Fix Send a non-empty Idempotency-Key header of at most 256 characters.
https://agentisend.com/docs/errors#invalid_idempotency_key
missing_required_field422 · not retryable
Body is missing required fields.
Fix Include from, to and subject in POST /emails.
https://agentisend.com/docs/errors#missing_required_field
invalid_from_address422 · not retryable
The from field is not a valid address.
Fix Use a plain address or "Name <addr@domain>" format in POST /emails.
https://agentisend.com/docs/errors#invalid_from_address
invalid_parameter422 · not retryable
A parameter has an invalid value.
Fix Correct the named parameter and retry.
https://agentisend.com/docs/errors#invalid_parameter
invalid_cursor400 · not retryable
This page cursor is no longer valid.
Fix Call the list again without a cursor, or pass the next_cursor from a page you still have.
https://agentisend.com/docs/errors#invalid_cursor
invalid_attachment422 · not retryable
Each attachment needs content (base64) or path.
Fix Provide attachment.content or attachment.path in POST /emails.
https://agentisend.com/docs/errors#invalid_attachment
invalid_region422 · not retryable
Region must be one of us, eu.
Fix Pass region as us (Oregon) or eu (Helsinki) in POST /domains. Omitting it stores us. For this release us-east-1, sa-east-1 and ap-northeast-1 map to us, and eu-west-1 maps to eu.
https://agentisend.com/docs/errors#invalid_region
tracking_subdomain_unverified422 · not retryable
Click and open tracking need a verified tracking host on this domain. Links were sent as written.
Fix Publish the tracking CNAME shown by GET /domains/:id, then POST /domains/:id/verify. Tracking starts on the next send.
https://agentisend.com/docs/errors#tracking_subdomain_unverified
tracking_subdomain_cannot_be_removed422 · not retryable
The tracking subdomain can be changed, never removed.
Fix Pass a new label such as "clicks" in PATCH /domains/:id. To stop counting opens and clicks, turn those switches off instead.
https://agentisend.com/docs/errors#tracking_subdomain_cannot_be_removed
domain_field_immutable422 · not retryable
Name, region, and return-path cannot change on an existing domain.
Fix Add a new domain with POST /domains. PATCH /domains/:id accepts click_tracking, open_tracking, and tracking_subdomain only.
https://agentisend.com/docs/errors#domain_field_immutable
open_tracking_on_transactional422 · not retryable
Open tracking on transactional mail can make inbox providers treat receipts and alerts as marketing.
Fix Leave open tracking off for receipts, password resets, and alerts. Turn it on for broadcasts if you want open counts.
https://agentisend.com/docs/errors#open_tracking_on_transactional
domain_already_exists409 · not retryable
That domain is already registered on this account.
Fix Use the existing domain from GET /domains, or remove it with DELETE /domains/:id first.
https://agentisend.com/docs/errors#domain_already_exists
domain_verified_elsewhere409 · not retryable
This domain is already verified on another account.
Fix Contact support to move the domain. We cannot verify it here while another account already has it verified.
https://agentisend.com/docs/errors#domain_verified_elsewhere
domain_not_verified403 · not retryable
Domain is not verified for sending.
Fix Add the DNS records shown by GET /domains/:id, then call POST /domains/:id/verify.
https://agentisend.com/docs/errors#domain_not_verified
account_suspended403 · not retryable
This account is suspended.
Fix Suspensions follow the published enforcement policy (docs/TRUST-SAFETY). Contact support to appeal; unused prepaid balance is refunded on termination.
https://agentisend.com/docs/errors#account_suspended
account_sandboxed403 · not retryable
This account is in the sandbox and may only send to its own verified domains.
Fix Verify the recipient domain with POST /domains + POST /domains/:id/verify, or file POST /trust/appeal for a person to review this account.
https://agentisend.com/docs/errors#account_sandboxed
trust_throttled429 · not retryable
This account is being throttled by the trust ladder.
Fix Send volume is temporarily capped because deliverability metrics crossed a published threshold. Check GET /trust/standing for the metric and value, file POST /trust/appeal if this is unexpected.
https://agentisend.com/docs/errors#trust_throttled
suppressed_recipient422 · not retryable
Recipient is on the account suppression list.
Fix GET /suppressions says which address and why. A hard bounce you have fixed can be cleared with DELETE /suppressions/:id; an unsubscribe or a spam complaint cannot — that address asked not to be contacted.
https://agentisend.com/docs/errors#suppressed_recipient
missing_api_key401 · not retryable
Missing API key in authorization header.
Fix Sign in at /login so the console sends its session cookie, or create a key with POST /api-keys and send "Authorization: Bearer as_...".
https://agentisend.com/docs/errors#missing_api_key
session_required401 · not retryable
You are signed out.
Fix Sign in to the console, then retry. API keys cannot call this route.
https://agentisend.com/docs/errors#session_required
human_action_required403 · not retryable
This is a person’s decision, so an API key cannot make it.
Fix Ask whoever runs this account to do it in the console. Scoping the key differently does not change the answer, and retrying fails the same way.
https://agentisend.com/docs/errors#human_action_required
csrf_origin_rejected403 · not retryable
This request came from a page on another site, and it changes data.
Fix Call the API with an API key (Authorization: Bearer …) instead of a session cookie, or make the request from the console. Create a key in the console under Settings, API keys.
https://agentisend.com/docs/errors#csrf_origin_rejected
mfa_required401 · not retryable
This session has not completed two-factor authentication.
Fix Finish signing in at /verify with a code from your authenticator app, or one of your recovery codes. Manage the second factor in the console under Settings, Security.
https://agentisend.com/docs/errors#mfa_required
billing_not_configured503 · not retryable
Billing is not configured on this deployment.
Fix The operator must set STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET (docs/STRIPE.md §4). Until then nothing can be bought; GET /billing/plan still answers and the 14-day Pro trial still starts.
https://agentisend.com/docs/errors#billing_not_configured
plan_not_purchasable400 · not retryable
This tier cannot be bought through checkout.
Fix Pass one of the tier ids listed under `plans` by GET /billing/plan (starter, pro, scale) to POST /billing/checkout.
https://agentisend.com/docs/errors#plan_not_purchasable
plan_required402 · not retryable
This account has no plan in force, so real email is not sent.
Fix A person on this account chooses a plan, or starts the 14-day Pro trial, in the console under Settings → Billing. Simulation sends keep working meanwhile.
https://agentisend.com/docs/errors#plan_required
trial_already_used409 · not retryable
This account has already used its 14-day Pro trial.
Fix Choose a plan in the console under Settings → Billing; POST /billing/checkout starts the payment.
https://agentisend.com/docs/errors#trial_already_used
plan_already_active409 · not retryable
This account already has a plan in force.
Fix Nothing to start. GET /billing/plan shows the plan, and plan changes are made in the console under Settings → Billing.
https://agentisend.com/docs/errors#plan_already_active
term_not_on_sale409 · not retryable
That billing term is not available to buy yet.
Fix Pass one of the terms listed under `terms_on_sale` by GET /billing/plan (monthly and yearly) to POST /billing/checkout.
https://agentisend.com/docs/errors#term_not_on_sale
subscription_active409 · not retryable
This account already has a live subscription.
Fix Change plans with POST /billing/portal — the Stripe customer portal prorates the change and shows the amount before it is confirmed. Checkout is only for an account with no subscription.
https://agentisend.com/docs/errors#subscription_active
billing_customer_missing404 · not retryable
This account has no billing customer yet.
Fix Start a subscription with POST /billing/checkout first; the customer portal only exists once a checkout has run.
https://agentisend.com/docs/errors#billing_customer_missing
stripe_signature_invalid400 · not retryable
The Stripe-Signature header did not verify against this endpoint’s secret.
Fix Only Stripe calls POST /webhooks/stripe. If you are Stripe: the endpoint secret configured as STRIPE_WEBHOOK_SECRET must be the whsec_ of THIS endpoint in THIS mode (test and live differ), and the body must be delivered unmodified.
https://agentisend.com/docs/errors#stripe_signature_invalid
invalid_api_key403 · not retryable
API key is invalid or revoked.
Fix Create a new key with POST /api-keys; deleted keys cannot be restored.
https://agentisend.com/docs/errors#invalid_api_key
restricted_api_key403 · not retryable
This API key is restricted to sending only.
Fix Use a full_access key (POST /api-keys with permission=full_access) for management endpoints.
https://agentisend.com/docs/errors#restricted_api_key
insufficient_role403 · not retryable
Your role on this account cannot make this change.
Fix Ask an owner to make the change, or to raise your role with PATCH /team/members/:id.
https://agentisend.com/docs/errors#insufficient_role
last_owner_required422 · not retryable
An account must keep at least one owner.
Fix Promote another member to owner with PATCH /team/members/:id first, then retry.
https://agentisend.com/docs/errors#last_owner_required
seat_limit_reached422 · not retryable
This plan has no seat left for another member.
Fix Remove a member with DELETE /team/members/:id, cancel a pending invite with DELETE /team/invites/:id, or move to a plan with more seats. Seats are never billed per seat.
https://agentisend.com/docs/errors#seat_limit_reached
invite_not_valid422 · not retryable
This invitation is expired, cancelled, or already accepted.
Fix Ask an owner or admin to send a new one with POST /team/invites.
https://agentisend.com/docs/errors#invite_not_valid
invite_email_mismatch403 · not retryable
This invitation was sent to a different address than the one you are signed in as.
Fix Sign out, sign in as the invited address, then open the invitation link again — POST /invite/:token/accept binds the membership to the signed-in address.
https://agentisend.com/docs/errors#invite_email_mismatch
already_in_account409 · not retryable
This address already belongs to an account.
Fix Leave the current account first, or ask the inviter to send the invitation to an address that has no account.
https://agentisend.com/docs/errors#already_in_account
domain_scope_violation403 · not retryable
This API key may only send from its scoped domain.
Fix Send from the scoped domain, or create a key without a domain scope via POST /api-keys.
https://agentisend.com/docs/errors#domain_scope_violation
not_found404 · not retryable
Endpoint or resource does not exist.
Fix Check the path against GET /openapi.json and the resource id against your account.
https://agentisend.com/docs/errors#not_found
session_expired404 · not retryable
This connection to AgentiSend has expired, so nothing was run. Reconnect your AI client and try again.
Fix Reconnect your AI client so it opens a new connection, then retry the request.
https://agentisend.com/docs/errors#session_expired
payload_too_large413 · not retryable
Request body is larger than this endpoint accepts.
Fix Send a smaller body. Limits are per endpoint — /mcp accepts 1 MB per JSON-RPC call, and attachments belong on POST /emails, which accepts 40 MB after base64.
https://agentisend.com/docs/errors#payload_too_large
unsupported_media_type415 · not retryable
This endpoint does not accept that content type.
Fix Send the body as JSON with `Content-Type: application/json`.
https://agentisend.com/docs/errors#unsupported_media_type
method_not_allowed405 · not retryable
Method not allowed for this path.
Fix Use a method listed in Allow for this route.
https://agentisend.com/docs/errors#method_not_allowed
idempotency_in_flight409 · retry after 5s
A request with this Idempotency-Key is still in progress.
Fix Wait and retry with the same Idempotency-Key to receive the original response.
https://agentisend.com/docs/errors#idempotency_in_flight
idempotency_payload_mismatch409 · not retryable
Same Idempotency-Key was used with a different payload.
Fix Reuse the exact same body for retries, or send a new Idempotency-Key for a new request.
https://agentisend.com/docs/errors#idempotency_payload_mismatch
agent_budget_exceeded402 · not retryable
Key budget for the current period is exhausted.
Fix Wait for the period to reset — get_agent_budget and GET /limits/keys/:id both say when. Raising a budget is a person’s decision, made in the console; a key cannot raise its own.
https://agentisend.com/docs/errors#agent_budget_exceeded
plan_limit_reached402 · not retryable
This account has used every email included in its plan for the current period.
Fix Upgrade in Settings → Billing, or wait until the reset date in this error.
https://agentisend.com/docs/errors#plan_limit_reached
key_budget_exceeds_plan422 · not retryable
A key budget cannot be unlimited or larger than the emails this plan includes per month.
Fix Set a whole number at or below the plan inclusion, or upgrade in Settings → Billing.
https://agentisend.com/docs/errors#key_budget_exceeds_plan
domain_limit_reached422 · not retryable
This plan has no sending domain left.
Fix Delete a domain with DELETE /domains/:id, or upgrade in Settings → Billing.
https://agentisend.com/docs/errors#domain_limit_reached
rate_ceiling_exceeded429 · retry after 60s
Per-minute rate ceiling for this key is exhausted.
Fix Wait the seconds below and send the same request again. Raising the ceiling is a person’s decision, made in the console; a key cannot raise its own.
https://agentisend.com/docs/errors#rate_ceiling_exceeded
daily_quota_exceeded429 · not retryable
Account daily quota reached.
Fix Upgrade the plan or wait for the UTC reset; see GET /usage for what this account has spent.
https://agentisend.com/docs/errors#daily_quota_exceeded
monthly_quota_exceeded429 · not retryable
Account monthly quota reached.
Fix Upgrade the plan or wait for the cycle reset; see GET /usage for what this account has spent.
https://agentisend.com/docs/errors#monthly_quota_exceeded
rate_limit_exceeded429 · retry after 60s
Too many requests.
Fix Back off and retry honoring the Retry-After header.
https://agentisend.com/docs/errors#rate_limit_exceeded
approval_required403 · not retryable
This action requires human approval before it executes.
Fix It is waiting in the console approvals inbox; GET /agent-actions shows it and what it says. A person decides — the key that asked cannot approve itself.
https://agentisend.com/docs/errors#approval_required
trust_paused403 · not retryable
Sending is paused by the trust system.
Fix Review reasons via GET /trust/standing, then file an appeal via POST /trust/appeal.
https://agentisend.com/docs/errors#trust_paused
kill_switch_active403 · not retryable
This API key has been paused with the kill switch.
Fix Read GET /trust/standing for why it was paused. Only a person signed in to the console can resume it; the paused key cannot resume itself.
https://agentisend.com/docs/errors#kill_switch_active
internal_server_error500 · not retryable
Unexpected error.
Fix Retry ONCE after a short pause, with the same Idempotency-Key so the retry cannot double-send. If it fails again, stop retrying and report the x-request-id from the response — that id is what identifies this exact failure in support.
https://agentisend.com/docs/errors#internal_server_error
support_ticket_not_found404 · not retryable
That request does not exist.
Fix Open Support in the console and pick a request from the list, or start a new one.
https://agentisend.com/docs/errors#support_ticket_not_found
support_closed409 · not retryable
This request is closed, so a reply cannot be added to it.
Fix Start a new request from Support in the console. If this one was resolved in the last 14 days, reopen it first.
https://agentisend.com/docs/errors#support_closed
support_reopen_expired409 · not retryable
This request can no longer be reopened.
Fix A request can be reopened within 14 days of being marked resolved. Start a new request from Support in the console.
https://agentisend.com/docs/errors#support_reopen_expired
support_merge_conflict409 · not retryable
These requests belong to different accounts and cannot be merged.
Fix Merge only requests from the same account.
https://agentisend.com/docs/errors#support_merge_conflict
support_upload_rejected400 · not retryable
That file cannot be attached.
Fix Attach a screenshot, PDF, CSV or log file up to 10 MB. Up to 5 files, 25 MB in total, per message.
https://agentisend.com/docs/errors#support_upload_rejected
support_upload_too_large413 · not retryable
That file is larger than 10 MB, or the files together are larger than 25 MB.
Fix Remove a file or send a smaller one. Each file must be 10 MB or smaller, and the message 25 MB in total.
https://agentisend.com/docs/errors#support_upload_too_large
support_attachment_expired410 · not retryable
This file has expired. Attachments are kept for 30 days.
Fix Ask the person who uploaded it to send the file again on the request.
https://agentisend.com/docs/errors#support_attachment_expired
support_rate_limited429 · retry after 3600s
Too many support requests from this account just now.
Fix Wait and try again. You can open 5 new requests an hour and send 30 replies an hour.
https://agentisend.com/docs/errors#support_rate_limited