Browse the docs

Error catalogue

122 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.

Codes from signing in, the session and a second factor.

cannot_receive_mail400 · not retryable

We could not find a mail server for that address. Check the spelling and try again.

Fix Correct the address and POST /api/auth/request-code again.

https://agentisend.com/docs/errors#cannot_receive_mail

invalid_credentials400 · not retryable

Invalid email or code.

Fix Check the address and the 6-digit code, or request a fresh code via POST /api/auth/request-code.

https://agentisend.com/docs/errors#invalid_credentials

code_expired400 · not retryable

This code has expired.

Fix Request a new code via POST /api/auth/request-code and verify within 15 minutes.

https://agentisend.com/docs/errors#code_expired

rate_limited429 · retry after 60s

Too many attempts. Please try again later.

Fix Wait, then retry. If you are locked out of verification, the lock clears itself.

https://agentisend.com/docs/errors#rate_limited

account_suspended403 · not retryable

This account is suspended.

Fix Read the enforcement policy at https://agentisend.com/policy/enforcement, then contact hello@agentisend.com to appeal.

https://agentisend.com/docs/errors#account_suspended

email_send_failed503 · retry after 30s

Your account is fine — we just couldn't get the sign-in email out right now. Please request a new code in a moment and it should come through.

Fix Wait 30s, then request a new code via POST /api/auth/request-code. The code you already have stays valid for 15 minutes either way.

https://agentisend.com/docs/errors#email_send_failed

internal_error500 · retry after 30s

That didn't work just now — please try again in a moment.

Fix Retry the request. If it keeps failing, write to hello@agentisend.com.

https://agentisend.com/docs/errors#internal_error

oauth_state_mismatch400 · not retryable

Sign-in could not be verified — the request did not originate from this server.

Fix Start again from GET /api/auth/google/start; do not reuse or edit the link that opened sign-in.

https://agentisend.com/docs/errors#oauth_state_mismatch

oauth_flow_expired400 · not retryable

This sign-in attempt has expired or was already completed.

Fix Start again from GET /api/auth/google/start.

https://agentisend.com/docs/errors#oauth_flow_expired

oauth_code_replayed400 · not retryable

This authorization code was already redeemed.

Fix Start again from GET /api/auth/google/start. One code signs you in exactly once.

https://agentisend.com/docs/errors#oauth_code_replayed

oauth_access_denied400 · not retryable

Google sign-in was cancelled before it finished.

Fix Start again from GET /api/auth/google/start, or sign in with an email code via POST /api/auth/request-code.

https://agentisend.com/docs/errors#oauth_access_denied

oauth_provider_error400 · not retryable

Google did not complete the sign-in.

Fix Start again from GET /api/auth/google/start, or sign in with an email code via POST /api/auth/request-code.

https://agentisend.com/docs/errors#oauth_provider_error

oauth_disabled403 · not retryable

Google sign-in is not turned on.

Fix Sign in with an email code via POST /api/auth/request-code.

https://agentisend.com/docs/errors#oauth_disabled

google_token_exchange_failed503 · not retryable

Google did not complete the sign-in.

Fix Retry sign-in from GET /api/auth/google/start.

https://agentisend.com/docs/errors#google_token_exchange_failed

google_id_token_invalid400 · not retryable

The identity asserted by Google could not be validated.

Fix Retry sign-in from GET /api/auth/google/start.

https://agentisend.com/docs/errors#google_id_token_invalid

google_email_unverified403 · not retryable

The Google account email is not verified.

Fix Verify the email address with Google, then retry sign-in from GET /api/auth/google/start.

https://agentisend.com/docs/errors#google_email_unverified

unauthenticated401 · not retryable

No active session.

Fix Sign in via POST /api/auth/request-code, then POST /api/auth/verify-code.

https://agentisend.com/docs/errors#unauthenticated

mfa_reauth_required401 · not retryable

Fix Request a fresh email code, then open Settings, Security.

https://agentisend.com/docs/errors#mfa_reauth_required

mfa_already_enabled409 · not retryable

Two-factor authentication is already on for this account.

Fix Turn it off first with POST /api/auth/mfa/disable and a current code, then enrol again.

https://agentisend.com/docs/errors#mfa_already_enabled

mfa_code_invalid400 · not retryable

That code does not match.

Fix Type the current 6-digit code from the authenticator, or one unused recovery code. Each recovery code works once.

https://agentisend.com/docs/errors#mfa_code_invalid

mfa_not_enabled409 · not retryable

Two-factor authentication is not on for this account.

Fix Enrol an authenticator in Settings, Security first.

https://agentisend.com/docs/errors#mfa_not_enabled

mfa_required_by_account403 · not retryable

An Owner requires two-factor authentication of everyone on this account.

Fix Ask an Owner to turn the requirement off in Settings, Security before removing your own second factor.

https://agentisend.com/docs/errors#mfa_required_by_account

forbidden403 · not retryable

Only an Owner can change the two-factor requirement for this account.

Fix Ask an Owner to change it in Settings, Security.

https://agentisend.com/docs/errors#forbidden

validation_failed400 · not retryable

require_mfa must be true or false.

Fix Send require_mfa as true to require a second factor of everyone, or false to stop requiring it.

https://agentisend.com/docs/errors#validation_failed

Sign-in for agents

unsupported_response_type400

Only response_type=code is supported.

Fix Send response_type=code to GET /oauth/authorize; the implicit and password grants are not implemented.

https://agentisend.com/docs/errors#unsupported_response_type

missing_authorize_params400

client_id, redirect_uri and code_challenge are all required.

Fix Register the client with POST /oauth/register, then call GET /oauth/authorize with client_id, redirect_uri and a PKCE code_challenge.

https://agentisend.com/docs/errors#missing_authorize_params

pkce_method_unsupported400

code_challenge_method must be S256. The plain method is not accepted.

Fix Hash your code_verifier with SHA-256, base64url-encode it, and send code_challenge_method=S256.

https://agentisend.com/docs/errors#pkce_method_unsupported

unknown_client400

No client is registered under that client_id.

Fix Register the client again with POST /oauth/register and retry with the client_id it returns.

https://agentisend.com/docs/errors#unknown_client

redirect_uri_not_registered400

That redirect_uri is not one of the URIs registered for this client.

Fix Use a redirect_uri from the client registration, or register a new client with POST /oauth/register that includes it.

https://agentisend.com/docs/errors#redirect_uri_not_registered

pending_authorization_unresumable400

This sign-in link is no longer valid — it was already used, or it expired.

Fix Start the connection again from your AI client; a fresh link is issued each time.

https://agentisend.com/docs/errors#pending_authorization_unresumable

not_authenticated401

No signed-in user is attached to this request.

Fix Sign in first, then submit the consent form again from the page it was rendered on.

https://agentisend.com/docs/errors#not_authenticated

no_account400

The signed-in user does not belong to an AgentiSend account.

Fix Create or join an account in the AgentiSend console, then start the connection again from your AI client.

https://agentisend.com/docs/errors#no_account

no_scope_requested400

This connection asked for no permissions, so there is nothing to grant.

Fix Send a space-separated scope parameter to GET /oauth/authorize naming what the client needs — the supported scopes are listed at /.well-known/oauth-authorization-server under scopes_supported.

https://agentisend.com/docs/errors#no_scope_requested

consent_denied400

The account holder declined this connection.

Fix Ask the account holder to approve the permissions, or request fewer scopes and start the connection again.

https://agentisend.com/docs/errors#consent_denied

consent_cross_site403

The approval was submitted from a page on another site, so nothing was approved.

Fix Approve the connection on the AgentiSend page your AI client opened. If that page is gone, start the connection again from the client.

https://agentisend.com/docs/errors#consent_cross_site

consent_expired400

This approval page was already used or has expired, so nothing was approved.

Fix Start the connection again from your AI client and approve it on the page that opens.

https://agentisend.com/docs/errors#consent_expired

registration_payload_too_large400

The registration payload is larger than the 4 KB limit.

Fix Send only the RFC 7591 metadata fields to POST /oauth/register; drop any custom members.

https://agentisend.com/docs/errors#registration_payload_too_large

redirect_uris_required400

redirect_uris is required and must list at least one URI.

Fix Include a redirect_uris array in the POST /oauth/register body.

https://agentisend.com/docs/errors#redirect_uris_required

too_many_redirect_uris400

A client may register at most 20 redirect URIs.

Fix Register the URIs this client actually uses, or register separate clients with POST /oauth/register.

https://agentisend.com/docs/errors#too_many_redirect_uris

redirect_uri_insecure400

Each redirect_uri must be https, a private-use scheme, or a loopback address.

Fix Use https for hosted clients, a custom scheme for desktop clients, or http://127.0.0.1:<port> for local ones.

https://agentisend.com/docs/errors#redirect_uri_insecure

registration_rate_limited429

Too many client registrations from this address in the last hour.

Fix Reuse the client_id you already registered; POST /oauth/register accepts 10 new clients per hour per address.

https://agentisend.com/docs/errors#registration_rate_limited

unsupported_grant_type400

Only the authorization_code and refresh_token grants are supported.

Fix Send grant_type=authorization_code with a code_verifier, or grant_type=refresh_token, to POST /oauth/token.

https://agentisend.com/docs/errors#unsupported_grant_type

missing_code_grant_params400

code, redirect_uri, client_id and code_verifier are all required.

Fix Include all four fields in the POST /oauth/token body; PKCE is mandatory, so code_verifier is never optional.

https://agentisend.com/docs/errors#missing_code_grant_params

missing_refresh_grant_params400

refresh_token and client_id are both required.

Fix Include refresh_token and client_id in the POST /oauth/token body.

https://agentisend.com/docs/errors#missing_refresh_grant_params

authorization_code_unknown400

That authorization code does not exist.

Fix Start the flow again at GET /oauth/authorize; codes are single-use and cannot be recreated.

https://agentisend.com/docs/errors#authorization_code_unknown

authorization_code_replayed400

That authorization code has already been exchanged. Every token issued from it has been revoked.

Fix Start the flow again at GET /oauth/authorize and exchange the new code exactly once.

https://agentisend.com/docs/errors#authorization_code_replayed

authorization_code_expired400

That authorization code expired. Codes live for 5 minutes.

Fix Start the flow again at GET /oauth/authorize and exchange the code promptly.

https://agentisend.com/docs/errors#authorization_code_expired

authorization_code_client_mismatch400

That authorization code was issued to a different client.

Fix Exchange the code using the same client_id that requested it at GET /oauth/authorize.

https://agentisend.com/docs/errors#authorization_code_client_mismatch

authorization_code_redirect_mismatch400

The redirect_uri does not match the one the code was issued for.

Fix Send the identical redirect_uri you passed to GET /oauth/authorize, character for character.

https://agentisend.com/docs/errors#authorization_code_redirect_mismatch

pkce_verification_failed400

The code_verifier does not match the code_challenge this code was issued against.

Fix Send the same code_verifier whose SHA-256 you used as the code_challenge at GET /oauth/authorize.

https://agentisend.com/docs/errors#pkce_verification_failed

authorization_code_concurrent400

That authorization code was exchanged by a concurrent request.

Fix Use the tokens the other request returned. Do not retry this code.

https://agentisend.com/docs/errors#authorization_code_concurrent

refresh_token_unknown400

That refresh token does not exist.

Fix Start the flow again at GET /oauth/authorize to obtain a new refresh token.

https://agentisend.com/docs/errors#refresh_token_unknown

refresh_token_revoked400

That refresh token was revoked.

Fix Start the flow again at GET /oauth/authorize; a revoked connection cannot be resumed.

https://agentisend.com/docs/errors#refresh_token_revoked

refresh_token_expired400

That refresh token can no longer be used. A refresh token lasts 30 days, and a connection must be approved again 365 days after it was first approved.

Fix Reconnect from your assistant. Start the flow again at GET /oauth/authorize.

https://agentisend.com/docs/errors#refresh_token_expired

invalid_target400

That resource is not the assistant connection on this server.

Fix Send the resource for this server, or leave it out, and start again at GET /oauth/authorize.

https://agentisend.com/docs/errors#invalid_target

refresh_token_replayed400

That refresh token was already rotated. The whole grant has been revoked as a precaution.

Fix Start the flow again at GET /oauth/authorize, and store only the newest refresh token each rotation returns.

https://agentisend.com/docs/errors#refresh_token_replayed

refresh_token_concurrent400

That refresh token was rotated by a concurrent request.

Fix Use the tokens the other request returned. Do not retry this refresh token.

https://agentisend.com/docs/errors#refresh_token_concurrent

refresh_token_client_mismatch400

That refresh token belongs to a different client.

Fix Send the client_id the refresh token was issued to.

https://agentisend.com/docs/errors#refresh_token_client_mismatch

route_not_found404

No OAuth endpoint is mounted at that path and method.

Fix Read GET /.well-known/oauth-authorization-server for the endpoints this server actually exposes.

https://agentisend.com/docs/errors#route_not_found

server_error500

The authorization server could not complete that request. Nothing was issued.

Fix Retry in a few seconds; if it persists, start the connection again from your AI client.

https://agentisend.com/docs/errors#server_error

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

Glossary

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 or eu 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, tracking_subdomain, and tls_mode 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

header_replaced422 · not retryable

A header you set was replaced by the one this kind of send always carries.

Fix Nothing to do for this send. To use your own unsubscribe link, send without topic_id and set List-Unsubscribe in headers from a verified domain.

https://agentisend.com/docs/errors#header_replaced

html_clipped_by_gmail422 · not retryable

The HTML is over 102 KB, so Gmail shows only its first 102 KB. The rest, footer and unsubscribe link included, is behind "View entire message".

Fix Cut the HTML under 102 KB: inline less CSS, drop comments and whitespace, and link to long content instead of including it. POST /emails/lint checks it before you send.

https://agentisend.com/docs/errors#html_clipped_by_gmail

link_domain_listed422 · not retryable

A linked domain is on a public spam-domain list, so mailbox providers may filter this message.

Fix Link to a domain that is not listed, or ask the list to review the domain. Check a domain with POST /emails/preflight before sending.

https://agentisend.com/docs/errors#link_domain_listed

domain_already_exists409 · not retryable

That domain is already registered on this account.

Fix Use the existing domain from GET /domains. A person removes a domain in the console under Domains.

https://agentisend.com/docs/errors#domain_already_exists

domain_blocklisted422 · not retryable

This domain is on a public blocklist, so it cannot be added.

Fix Use a domain that is not listed, or wait until the listing is removed, then POST /domains again.

https://agentisend.com/docs/errors#domain_blocklisted

mailbox_provider_domain422 · not retryable

You cannot send as a mailbox provider’s domain.

Fix Add a domain you own with POST /domains, such as acme.com or mail.acme.com, and send from an address on it.

https://agentisend.com/docs/errors#mailbox_provider_domain

template_name_taken409 · not retryable

A template with this name already exists on this account.

Fix Choose another name, or edit the existing template with PATCH /templates/:id. GET /templates lists them with their ids.

https://agentisend.com/docs/errors#template_name_taken

template_alias_taken409 · not retryable

A template with this alias already exists on this account.

Fix Choose another alias, or remove it from the template that holds it with PATCH /templates/:id and alias set to null. GET /templates lists them with their aliases.

https://agentisend.com/docs/errors#template_alias_taken

template_in_use409 · not retryable

A broadcast that has not been sent yet still uses this template.

Fix Archive each broadcast named in the message with POST /broadcasts/:id/archive, then delete the template again.

https://agentisend.com/docs/errors#template_in_use

segment_in_use409 · not retryable

A broadcast that has not been sent or archived still sends to this segment.

Fix Archive each broadcast named in the message with POST /broadcasts/:id/archive, or give it another segment with PATCH /broadcasts/:id, then delete the segment again.

https://agentisend.com/docs/errors#segment_in_use

contact_resubscribe_required409 · not retryable

This address asked not to be contacted, so marking the contact active leaves that in place.

Fix POST /contacts/:id/resubscribe with consent_source and consent_at after the person opts back in. The id can be the contact id or the email address. A spam report is not lifted by that call.

https://agentisend.com/docs/errors#contact_resubscribe_required

email_still_scheduled409 · not retryable

This email is still scheduled or queued, so deleting it now would race the send.

Fix Cancel it first: POST /emails/:id/cancel, then delete it again.

https://agentisend.com/docs/errors#email_still_scheduled

sending_domain_blocked403 · not retryable

This domain cannot send through AgentiSend.

Fix Send from a different domain you own. If you believe this is a mistake, contact support and name the domain.

https://agentisend.com/docs/errors#sending_domain_blocked

young_domain_held403 · not retryable

Mail from this domain waits for a review. It was registered less than 30 days ago, or its registration date could not be read.

Fix Mail from your other verified domains still sends. Write to hello@agentisend.com and name this domain.

https://agentisend.com/docs/errors#young_domain_held

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_claimable409 · not retryable

This domain cannot be claimed.

Fix A claim moves a domain that another account has verified. If no one has verified it, add it with POST /domains. If it belongs to us or is blocked, write to hello@agentisend.com and name the domain.

https://agentisend.com/docs/errors#domain_not_claimable

domain_sending_disabled403 · not retryable

Sending is turned off for this domain.

Fix Turn it back on with PATCH /domains/:id and {"capabilities": {"sending": "enabled"}}, or send from another domain.

https://agentisend.com/docs/errors#domain_sending_disabled

inbound_sender_refused403 · not retryable

This sender is not allowed to write to this domain.

Fix Change who may write with POST /domains/:id/inbound-rules, or set inbound_policy with PATCH /domains/:id.

https://agentisend.com/docs/errors#inbound_sender_refused

domain_not_verified403 · not retryable

This sending domain is not verified.

Fix If it is pending, publish the required records from GET /domains/:id; checks continue for 72 hours. Test now by sending to an address ending in @simulator.agentisend.com. If it is not registered, POST /domains first. If it is failed, GET /domains/:id names the record to fix, then POST /domains/:id/verify to reopen the window.

https://agentisend.com/docs/errors#domain_not_verified

onboarding_recipient_not_a_member403 · not retryable

The onboarding sender can only mail this account's own members — the addresses they sign in with.

Fix Send to a member sign-in address, or verify a domain with POST /domains and send from that domain.

https://agentisend.com/docs/errors#onboarding_recipient_not_a_member

onboarding_shape_refused422 · not retryable

The onboarding sender does not accept cc, bcc, attachments, tracking, or extra headers.

Fix Omit those fields, or verify a domain with POST /domains and send from that domain.

https://agentisend.com/docs/errors#onboarding_shape_refused

onboarding_daily_cap_reached429 · retry after 86400s

This account has used its 20 onboarding emails for today.

Fix Wait until tomorrow (UTC), or verify a domain with POST /domains and send from that domain.

https://agentisend.com/docs/errors#onboarding_daily_cap_reached

onboarding_sender_unavailable403 · not retryable

The onboarding sender is not available.

Fix Send to an address ending in @simulator.agentisend.com, or verify a domain with POST /domains and send from that domain.

https://agentisend.com/docs/errors#onboarding_sender_unavailable

dns_unreachable503 · retry after 300s

The DNS lookup did not complete. This is not a problem with the records you published.

Fix Wait; checks continue on their own. Retry this call after the seconds given in Retry-After.

https://agentisend.com/what-does-dns-unreachable-mean#dns_unreachable

dkim_key_mismatch422 · not retryable

The DKIM selector is publishing a different key than the one issued for this domain.

Fix Replace that TXT record with the value shown on GET /domains/:id, then POST /domains/:id/verify.

https://agentisend.com/what-does-dkim-key-mismatch-mean#dkim_key_mismatch

domain_check_window_expired422 · not retryable

The 72-hour check window closed before the required DNS records resolved.

Fix Publish the required records from GET /domains/:id, then POST /domains/:id/verify. That reopens the window for another 72 hours.

https://agentisend.com/what-does-domain-check-window-expired-mean#domain_check_window_expired

return_path_subdomain_in_use409 · not retryable

The return-path host already has an MX record pointing somewhere else.

Fix Pass return_path_subdomain on POST /domains: a label of up to 63 characters that starts with a letter. send is the default; bounce is the usual choice when send already has an MX.

https://agentisend.com/docs/errors#return_path_subdomain_in_use

spf_conflict422 · not retryable

This domain already publishes an SPF record that does not include us.

Fix Replace the existing TXT with the merged record we return. This is advice: the domain can verify and send without the apex SPF once the return-path records resolve.

https://agentisend.com/what-does-spf-conflict-mean#spf_conflict

spf_lookup_limit422 · not retryable

Merging our include into the existing SPF record would pass the 10-lookup limit.

Fix Do not add a second SPF record. Rely on the return-path SPF, which is required anyway. The apex SPF is advice and never blocks sending.

https://agentisend.com/docs/errors#spf_lookup_limit

service_unavailable503 · not retryable

The API is temporarily unavailable — a dependency failed transiently.

Fix Retry after the seconds given in Retry-After. If it persists beyond a few minutes, check the public status page (GET /status) for the affected component.

https://agentisend.com/docs/errors#service_unavailable

account_suspended403 · not retryable

This account is suspended.

Fix Read the enforcement policy at https://agentisend.com/policy/enforcement, then contact hello@agentisend.com to appeal.

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/what-does-account-sandboxed-mean#account_sandboxed

Glossary

review_sandbox_recipient_only422 · not retryable

The review account sends only to addresses ending in @simulator.agentisend.com and to its own review addresses.

Fix Send to an address ending in @simulator.agentisend.com, or to reviewer@agentisend.com. Delivering to anyone else needs an account of your own: sign up at agentisend.com.

https://agentisend.com/docs/errors#review_sandbox_recipient_only

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/what-does-suppressed-recipient-mean#suppressed_recipient

Glossary

agent_signup_refused422 · not retryable

This address cannot start an agent sign-up.

Fix Use a real inbox that does not already have an account. If it does, sign in and mint a key.

https://agentisend.com/docs/errors#agent_signup_refused

agent_signup_code_rejected401 · not retryable

That code does not match.

Fix Enter the 6-digit code from the email, or POST /agent/sign-up again after it expires to send another.

https://agentisend.com/docs/errors#agent_signup_code_rejected

agent_unconfirmed403 · not retryable

This key can email only the human who has not confirmed it yet.

Fix POST /agent/verify with the 6-digit code the human received. Until then every recipient has to be that address.

https://agentisend.com/docs/errors#agent_unconfirmed

recipient_ramp403 · not retryable

This key has reached its recipient ramp.

Fix The next recipient slot opens at the time named in this response. POST /emails again after that. Until then, send only to recipients this key has already reached.

https://agentisend.com/docs/errors#recipient_ramp

content_refused422 · not retryable

This email was refused because of what it contains.

Fix The message names the field and what matched in it. Remove or change that part and send again. POST /emails/preflight runs the same check without sending anything.

https://agentisend.com/docs/errors#content_refused

recipient_blocklisted422 · not retryable

This recipient is blocked.

Fix Send to a different address. An address ending in @simulator.agentisend.com is never blocked.

https://agentisend.com/docs/errors#recipient_blocklisted

missing_api_key401 · not retryable

Missing API key in authorization header.

Fix Create an API key at https://console.agentisend.com/api-keys and send "Authorization: Bearer as_...". MCP clients can connect with OAuth instead of a key.

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

Glossary

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 https://console.agentisend.com/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

Purchases are unavailable right now.

Fix GET /billing/plan still works, and the account stays on Free.

https://agentisend.com/docs/errors#billing_not_configured

charge_not_this_account403 · not retryable

That payment does not belong to this account.

Fix Open the account and refund a payment listed on it.

https://agentisend.com/docs/errors#charge_not_this_account

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

overage_cap_reached402 · not retryable

This account has used every email in its plan and every extra email its owner allowed this period.

Fix Raise the overage ceiling or move up a plan in Settings → Billing, or wait until the reset date in this error.

https://agentisend.com/docs/errors#overage_cap_reached

overage_not_on_plan409 · not retryable

Overage is available on Starter, Pro and Scale. This account is on Free, which pauses at its inclusion.

Fix Choose a paid plan in Settings → Billing, then turn overage on.

https://agentisend.com/docs/errors#overage_not_on_plan

daily_limit_reached402 · not retryable

This account has sent its daily allowance of emails; sending resumes at 00:00 UTC.

Fix Wait for 00:00 UTC, or upgrade in Settings → Billing — every paid plan has no daily cap.

https://agentisend.com/docs/errors#daily_limit_reached

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 billing 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

portal_change_unavailable409 · not retryable

Switching to this plan isn't open from here yet.

Fix Write to Support and we will make the change for you.

https://agentisend.com/docs/errors#portal_change_unavailable

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 signature on this webhook did not verify.

Fix Only the billing service calls POST /webhooks/stripe. Use the signing secret for this endpoint in this mode, and deliver the body 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_limit_reached429 · retry after 3600s

This account has sent as many invitations as it may for now: 10 a day, and 3 to one address in 7 days.

Fix Wait the seconds given and invite again. A cancelled invitation still counts for 24 hours. Someone who already has an invitation can use the link in it.

https://agentisend.com/docs/errors#invite_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 List that resource on this account and use an id from the list. For a domain, GET /domains accepts the id or the domain name. A path that is not a route is a typo in the URL.

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. Most endpoints accept 1 MB. Sends (POST /emails, /emails/batch, replies) and template, broadcast and automation edits accept 50 MB, which fits 40 MB of attachments after base64. /mcp accepts 1 MB per JSON-RPC call.

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/what-does-idempotency-payload-mismatch-mean#idempotency_payload_mismatch

Glossary

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/what-does-agent-budget-exceeded-mean#agent_budget_exceeded

Glossary

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

Glossary

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

Glossary

domain_limit_reached422 · not retryable

This plan has no sending domain left.

Fix Remove a domain in the console under Domains, or upgrade in Settings → Billing.

https://agentisend.com/docs/errors#domain_limit_reached

dedicated_ip_assigned_by_us403 · not retryable

Dedicated IPs are assigned by us from the addresses we send from; the API cannot create one.

Fix Ask support for a dedicated IP (available on Scale, about $30 a month, warmup included). Once it is assigned, GET /dedicated-ips lists it and GET /dedicated-ips/ramp shows the warmup curve it follows.

https://agentisend.com/docs/errors#dedicated_ip_assigned_by_us

webhook_endpoint_limit_reached422 · not retryable

This account already has 20 webhook endpoints, the most one account can hold.

Fix Delete an endpoint you no longer use with DELETE /webhooks/:id, or send more event types to one you keep — an endpoint takes a list of events.

https://agentisend.com/docs/errors#webhook_endpoint_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/what-does-rate-ceiling-exceeded-mean#rate_ceiling_exceeded

Glossary

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

Glossary

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_limiter_unavailable503 · retry after 5s

The rate limiter could not be reached, so nothing was run.

Fix Retry in a few seconds. Nothing was sent and nothing was changed — writes are refused rather than run unmetered against a shared sending reputation.

https://agentisend.com/docs/errors#rate_limiter_unavailable

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

Glossary

approval_required403 · not retryable

This action requires human approval before it executes.

Fix Do not send it again: a person approves or rejects it in the console under Agents → Approvals, and approving sends it — the message then appears in GET /emails. action_id in this error names the held send; the key that asked cannot approve itself, and a retry waits on the same approval.

https://agentisend.com/what-does-approval-required-mean#approval_required

Glossary

approval_expired409 · not retryable

This hold has expired, so it cannot be approved.

Fix Send the message again if it should still go out. A hold lasts 24 hours unless the send named an earlier time.

https://agentisend.com/docs/errors#approval_expired

Glossary

staff_review_required403 · not retryable

This message looks like it comes from another company, so a person at AgentiSend reviews it before it is sent.

Fix Nothing else on your account is held. Write to hello@agentisend.com and name the message if it is urgent. You can cancel it instead.

https://agentisend.com/docs/errors#staff_review_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

Glossary

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/what-does-kill-switch-active-mean#kill_switch_active

Glossary

sending_paused_everywhere503 · retry after 300s

Sending is paused for every account while AgentiSend handles an incident. Nothing was sent or charged.

Fix Retry the same request, with the same Idempotency-Key, after the seconds given in Retry-After. Scheduled sends wait and go out once sending resumes.

https://agentisend.com/docs/errors#sending_paused_everywhere

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_reply_too_soon409 · not retryable

A public reply already went to this customer less than 2 minutes ago, so this one was not sent.

Fix Reload the request and read the latest reply. To send a second reply anyway, send it again with allow_rapid_second set to true.

https://agentisend.com/docs/errors#support_reply_too_soon

support_draft_unavailable503 · not retryable

Drafting a reply is not turned on for this support desk.

Fix Write the reply by hand. When drafting is off, it turns on once the server has a drafting key configured.

https://agentisend.com/docs/errors#support_draft_unavailable

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

appsumo_signature_invalid401 · not retryable

This notification could not be verified.

Fix Send the notification again from the partner portal. A request we cannot verify is refused.

https://agentisend.com/docs/errors#appsumo_signature_invalid

appsumo_license_linked409 · not retryable

This license is already on another account.

Fix Write to hello@agentisend.com with the license key.

https://agentisend.com/docs/errors#appsumo_license_linked

appsumo_license_inactive409 · not retryable

This license is not active.

Fix Finish activating it, then enter the license key again. If it stays inactive, write to hello@agentisend.com with the license key.

https://agentisend.com/docs/errors#appsumo_license_inactive

appsumo_license_not_confirmed400 · not retryable

That license key could not be confirmed.

Fix Check the key and try again. If it is correct, write to hello@agentisend.com with the license key.

https://agentisend.com/docs/errors#appsumo_license_not_confirmed

appsumo_ticket_invalid400 · not retryable

This redemption link has expired or was already used.

Fix Enter your AppSumo license key on the redemption page, or start again from AppSumo.

https://agentisend.com/docs/errors#appsumo_ticket_invalid

appsumo_lookup_limited429 · retry after 60s

License lookups are paused for a minute.

Fix Wait a minute and enter the license key again.

https://agentisend.com/docs/errors#appsumo_lookup_limited

lifetime_sold_on_appsumo409 · not retryable

Lifetime plans are on AppSumo.

Fix Buy a lifetime plan from the AppSumo deal linked in Settings → Billing.

https://agentisend.com/docs/errors#lifetime_sold_on_appsumo

sign_in_check_required400 · not retryable

Confirm you are a person before asking for another sign-in code.

Fix Complete the check on the sign-in page, then ask for another code with the token it returns.

https://agentisend.com/docs/errors#sign_in_check_required

PreviousSend email with Auth0 NextEvent catalogue

Error catalogue

Sign-in

validation_error400 · not retryable

cannot_receive_mail400 · not retryable

invalid_credentials400 · not retryable

code_expired400 · not retryable

rate_limited429 · retry after 60s

csrf_origin_rejected403 · not retryable

account_suspended403 · not retryable

email_send_failed503 · retry after 30s

internal_error500 · retry after 30s

oauth_state_mismatch400 · not retryable

oauth_flow_expired400 · not retryable

oauth_code_replayed400 · not retryable

oauth_access_denied400 · not retryable

oauth_provider_error400 · not retryable

oauth_disabled403 · not retryable

google_token_exchange_failed503 · not retryable

google_id_token_invalid400 · not retryable

google_email_unverified403 · not retryable

unauthenticated401 · not retryable

route_not_found404 · not retryable

mfa_reauth_required401 · not retryable

mfa_already_enabled409 · not retryable

mfa_code_invalid400 · not retryable

mfa_not_enabled409 · not retryable

mfa_required_by_account403 · not retryable

forbidden403 · not retryable

validation_failed400 · not retryable

Sign-in for agents

unsupported_response_type400

missing_authorize_params400

pkce_method_unsupported400

unknown_client400

redirect_uri_not_registered400

pending_authorization_unresumable400

not_authenticated401

no_account400

no_scope_requested400

consent_denied400

consent_cross_site403

consent_expired400

registration_payload_too_large400

redirect_uris_required400

too_many_redirect_uris400

redirect_uri_insecure400

registration_rate_limited429

unsupported_grant_type400

missing_code_grant_params400

missing_refresh_grant_params400

authorization_code_unknown400

authorization_code_replayed400

authorization_code_expired400

authorization_code_client_mismatch400

authorization_code_redirect_mismatch400

pkce_verification_failed400

authorization_code_concurrent400

refresh_token_unknown400

refresh_token_revoked400

refresh_token_expired400

invalid_target400

refresh_token_replayed400

refresh_token_concurrent400

refresh_token_client_mismatch400

route_not_found404

server_error500

Every code

validation_error400 · not retryable

invalid_idempotency_key400 · not retryable

missing_required_field422 · not retryable

invalid_from_address422 · not retryable

invalid_parameter422 · not retryable

invalid_cursor400 · not retryable

invalid_attachment422 · not retryable

invalid_region422 · not retryable

tracking_subdomain_unverified422 · not retryable

tracking_subdomain_cannot_be_removed422 · not retryable

domain_field_immutable422 · not retryable

open_tracking_on_transactional422 · not retryable

header_replaced422 · not retryable