Error codes

The AY Inbox API uses standard HTTP status codes and returns structured error responses in JSON format.

Error response format

All errors follow this structure:

{
  "error": "Error Type",
  "message": "Human-readable description of what went wrong.",
  "code": "machine_readable_code",
  "request_id": "req_or_uuid_for_support"
}

error and message are for people. Client logic should use code, HTTP status, and endpoint-specific fields such as retry_after. Include request_id when contacting support. A few codes also carry an optional reason, a finer key for when the same code has more than one next step; each is listed with its code, and a client should treat an unknown or missing reason as the plain code.

HTTP status codes

Send-admission diagnostics

These codes appear in campaign activity and task failure metadata, not as HTTP response codes:

Admission denial before dispatch releases the send reservation without spending a failed-send attempt. A refused unibox send ends with status failed, is not retried, and is reported to the mailbox owner. See campaigns and sending behavior for the separate configurable ceilings and daily targets.

Client errors (4xx)

Server errors (5xx)

Error details

400 Bad Request

Returned when the request cannot be processed due to invalid syntax.

Common causes:

• Invalid JSON in request body
• Missing required fields
• Invalid field types
• Values outside allowed ranges

Example:

{
  "error": "Bad Request",
  "message": "The request body is missing or has invalid fields: \"to\" is required; \"subject\" is required.",
  "code": "bad_request",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

When the body cannot be read, the message says why:

Fields are named by their JSON key, with nested fields as a dotted path (inner.name). The code is bad_request in every case, so branch on code and show or log message.

Versioned API routes check every query parameter name and value before the endpoint runs, including endpoints that read filters directly. The legacy /invitations/lookup alias applies the same validation. NUL characters, invalid UTF-8 and malformed query encoding return 400 rather than sending unsupported text to the database. For example, ?q=%00 returns Query parameter "q[0]" contains a NUL character, which is not supported. Valid Unicode text and properly encoded punctuation remain unchanged.

Every route takes each query parameter at most once. A parameter repeated in the query string returns 400 with code: "duplicate_query_parameter" and a request_id, whatever the values, and the message names it: The query parameter "status" appears more than once. Send it once per request. The parameters documented as lists accept repeats: status on GET /v1/advisor/recommendations, and campaign_ids and folder_ids on GET /v1/analytics/dashboard. Send any other list as one comma-separated value where the endpoint documents one.

A request carrying more than one Authorization, X-Ayinbox-Token, Idempotency-Key or Origin header line returns 400 with code: "duplicate_header", and the message names the header. Send each of them once. Repeated X-Forwarded-For lines are read as one list in arrival order, and for X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port and X-Real-IP the last line is used, the one the nearest proxy wrote. Forwarded headers are believed only from TRUSTED_PROXIES.

The public forms service answers its /api/forms/ routes with error and code holding the same slug, and a message to show:

{
  "error": "stale_page",
  "message": "This page has been open too long. Reload it and try again.",
  "code": "stale_page"
}

Resource IDs on email, campaign and contact routes must be UUIDs. Email tags and campaign email_tags and folders arrays also require UUID values. Malformed values return 400 with code: "bad_request" and a request_id before a database write. Valid UUIDs are normalized and repeated relation IDs are deduplicated; workspace ownership checks still apply.

How to fix:

• Check that your JSON is valid
• Verify all required fields are present
• Ensure field values match expected types
• Compare the body's shape with the endpoint's reference page: some endpoints take an array, most take an object

Specific 400 codes:

Image upload refusals

Avatars, OAuth app logos, form logos, covers and backgrounds, and images placed in an email are checked by what the file contains, not by its name or the type the browser sends.

{
  "error": "Bad Request",
  "message": "The avatar could not be read as an image. The file looks damaged, or it is a different format than its name suggests. Upload a PNG or JPG file up to 2 MB and 1024px on each side.",
  "code": "image_unreadable",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

Password refusals

A password must be 8 to 128 characters. There is no composition rule, but it is checked against the 100,000 most commonly breached passwords published by the UK National Cyber Security Centre, case-insensitively.

{
  "error": "Bad Request",
  "message": "This password appears in a public list of breached passwords. Choose one that does not.",
  "code": "password_breached",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

App Attest refusals

The native app proves itself with App Attest in place of the captcha on sign-in, registration and password reset.

Each registered key may make 30 protected calls per hour. Past that the call answers 400 with code bad_request and the message Too many attempts, please try again later., the same answer as the other sign-in attempt budgets.

{
  "error": "Bad Request",
  "message": "We couldn’t verify this copy of the app. Update it from the App Store and try again.",
  "code": "app_attest_failed",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

Cloud connection refusals

AY Inbox Cloud pool link

These come from AY Inbox Cloud's side of the connection (/v1/pool-link/*), which a self-hosted instance calls on your behalf. The instance passes the code and message through, so they can reach you from the instance's own settings and mailbox screens too.

CLI sign-in

ayinbox auth login signs the CLI in with a one-time code (POST /auth/cli/code, POST /auth/cli/poll, and the dashboard's approval page). See the CLI.

AY Inbox Cloud warmup refusals

A mailbox warmed by AY Inbox Cloud has its warmup settings changed through the cloud (see warmup settings). PATCH /emails/:id and the warmup start, pause and resume routes answer with these when that cannot happen. In every case the rest of the patch is not applied on the instance. After cloud_warmup_not_applied, the mailbox's copy of its AY Inbox Cloud settings is still refreshed to what AY Inbox Cloud reported. A replay with the same Idempotency-Key returns the stored answer, so retry with a new key.

Consent list refusals

Name refusals

Names are shown to other people, including in invitation and notification emails, so they carry plain text only. The same rules apply to the dashboard, the API, the setup page and ayinboxctl:

• a first or last name is at most 50 characters and contains a letter; a workspace or company name is at most 64 characters and contains a letter or a number; a mailbox display name keeps its own 2 to 100 character bound
• no links, web addresses or email addresses: nothing with @, //, www. or a scheme such as https:, no hostname such as example.com, and no IP address. Full-width and ideographic dots count as dots
• no control characters, invisible formatting characters (zero-width and bidirectional overrides), <, >, ` or \, and no more than three stacked combining marks
• leading and trailing spaces are trimmed and runs of spaces become one, and that is the form stored
• an OAuth app name cannot include AY Inbox, spaced out or spelled with look-alike characters included. An app that already had such a name keeps it until the name is changed

{
  "error": "Bad Request",
  "message": "First name cannot contain a link, web address or email address.",
  "code": "invalid_name",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

A name from Google, Apple or a single sign-on provider that breaks these rules is dropped rather than refusing the sign-in, and you are asked for it during onboarding.

Redirect destination refusals

A redirect may only send visitors to a page on one of the workspace's own domains, or a subdomain of one:

• a domain the workspace has a mailbox on, other than a shared email provider such as gmail.com
• a verified tracking host of one of its mailboxes
• the workspace's custom forms domain, once it is verified
• a website the workspace confirmed by publishing its _ayinbox TXT record on the website's registrable domain. Saving looks for the record before refusing, and POST /emails/domains/:domain/redirect/website returns the record to publish. See confirm your website

Hosts are compared in lowercase, without a trailing dot and in their ASCII form, so bücher.de and xn--bcher-kva.de are the same domain. A subdomain matches its parent (shop.acme.com is on acme.com), but a name that only starts or ends the same way does not (acme.com.example.net and notacme.com are not on acme.com). An empty value still means no redirect.

{
  "error": "Bad Request",
  "message": "The redirect has to go to a page on one of this workspace's own domains: a domain it has a mailbox on (not a shared provider such as gmail.com), its verified tracking domain, its verified forms domain, a website it verified with its TXT record, or a subdomain of one of them. Verify the website under Sending domains > Redirect, or use an address on one of those.",
  "code": "redirect_target_not_own_domain",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

A destination saved earlier that no longer passes, because the workspace removed its last mailbox on that domain for example, is kept but not used: see the forms guide and root redirects.

Mailbox import refusals

The mailbox import routes (/emails/imports) answer these. A row that fails to connect is not an HTTP error: the import carries it, with its reason in the row's cause (listed in the guide).

{
  "error": "Conflict",
  "message": "This row's credentials were removed after the retry window. Import it again.",
  "code": "mailbox_import_credentials_expired",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

Mailbox source refusals

The inbox vendor routes (/emails/vendors), the admin grant routes (/emails/grants) and the sending domain routes (/emails/domains) answer these. Inside an import, the vendor and grant failures land on the row instead, as its cause (see the guide).

{
  "error": "Bad Request",
  "message": "This sign-in expired or belongs to someone else. Start again.",
  "code": "mailbox_grant_state_invalid",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

App password switch refusals

POST /emails/onboarding/app-password/:id moves a mailbox off per-mailbox Google sign-in onto an app password. Besides these, a password Gmail refuses answers with the same codes as an SMTP/IMAP connect, such as mailbox_auth_refused. Nothing is changed on any refusal.

Placement test refusals

The inbox placement test routes (/placement/* and /campaigns/:id/placement-monitor) answer these. A refused test sends nothing: every check runs before the first copy is scheduled.

A batch runs every check that applies to the whole batch (the copy, the panel, the tracking, the allowance and the credits agreed) before it is created, and refuses with the codes above. The checks for each mailbox run when its turn comes: a mailbox refused then is deferred or skipped, and its sender row in GET /placement/batches/:id/senders carries the code as reason with its sentence as detail. Besides the single-test codes, a sender row can carry placement_sender_deleted (the mailbox was removed from the workspace), placement_batch_retry_expired (still unavailable when the seven-day retry window closed), placement_batch_start_failed (the test could not be started after several tries) and placement_batch_copy_unavailable (the campaign or step being tested was deleted, which skips every mailbox not started yet).

{
  "error": "Conflict",
  "message": "This test sends 40 emails from [email protected], which has 12 left of its daily limit today.",
  "code": "placement_daily_budget",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

A 400 without one of these codes is a malformed request: an unknown panel or tracking, a sequence_id without its campaign_id, a missing subject or body on an ad-hoc test, a monitor interval_days outside 1 to 30 or an alert_below outside 0 to 100, or on a batch pace quick, both or neither of sender_account_ids and sender_scope, an unknown sender_scope.type, sample.mode or on_unavailable, or sample.stratify on a sample that is not random or percent.

OAuth app and community directory refusals

POST /oauth/applications registers an app and PUT /oauth/applications/:id/listing publishes or edits its community directory listing. Nothing is saved on any refusal.

Credential management refusals

The OAuth consent and token endpoints answer in the RFC 6749 shape (error, error_description) instead. access_denied from GET /oauth/authorize/details or POST /oauth/authorize means the approving member's role covers none of the requested scopes. invalid_grant on a refresh means the token is unknown, expired, revoked, was already used (which also revokes the grant), or its member no longer holds any of its scopes. 400 invalid_request from POST /oauth/token or POST /oauth/revoke includes a form that sends any parameter more than once (RFC 6749 section 3.2). A failure inside the server is 500 server_error with a fixed description and a request_id.

CRM provider refusals

Returned by the CRM endpoints while a workspace runs its CRM on HubSpot or Pipedrive. A change is written to the provider before it is saved in AY Inbox, so each of these means nothing was changed on either side.

{
  "error": "Conflict",
  "message": "Pipelines are managed in HubSpot. Edit them there and they update here within minutes.",
  "code": "crm_managed_externally",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

Salesforce sync refusals

The Salesforce endpoints answer with their own codes. When Salesforce itself refused, message carries its errorCode and text, such as Salesforce: INVALID_FIELD: No such column 'Tier__c' on entity 'Lead'.

Apollo and Clay refusals

The Apollo and Clay endpoints answer with their own codes.

Lead scoring refusals

The lead scoring endpoints answer with their own codes.

Campaign brain refusals

The campaign brain routes and the drafts that read a brain answer with their own codes.

Auto-reply refusals

The auto-reply routes and their agent tools answer with these codes.

Calendar booking refusals

The calendar booking routes answer with these codes. A provider's own response never reaches the caller; it stays in the server log against the request id.

Company signal refusals

The company signal endpoints answer with their own codes.

First-line job refusals

POST /contacts/first-lines starts a first-line job and answers these codes, as does the list endpoint for its limit. A job that started and then stopped (out of credits, a spend limit, an empty Looot balance) is not a refusal: it ends with status: "error" and says why in last_error.

Automation refusals

mailbox_oauth_return_origin

A 400 with code: "mailbox_oauth_return_origin" means a Google or Microsoft mailbox connect or reauthorization came from a dashboard origin the backend does not allow. Add its exact HTTP(S) origin to CORS_ALLOW_ORIGINS, as in shared-backend dashboard configuration. A wildcard is not an OAuth return allowlist.

401 Unauthorized

Returned when authentication fails.

Common causes:

• Missing Authorization header
• Invalid API key format
• Expired API key
• Revoked API key

Example:

{
  "error": "Unauthorized",
  "message": "Token not found.",
  "code": "unauthorized",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

How to fix:

• Include the Authorization: Bearer aybox_... header
• Verify your API key is correct
• Check if your key has expired or been revoked
• Generate a new key if necessary

session_ended means the dashboard session behind the token was signed out, revoked, or ended by a password change. Refreshing will not help; sign in again.

{
  "error": "Unauthorized",
  "message": "Your session has ended. Sign in again to continue.",
  "code": "session_ended",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

Two more 401 variants are not about API keys at all. setup_token_invalid is returned by the first-run claim endpoint when the setup link is invalid, already used or expired. Print a new one with ayinboxctl setup-link, described in first run.

sso_wrong_browser is returned by POST /auth/sso/exchange when the handoff code is collected without the binding secret that POST /auth/<provider>/begin handed the browser that started the sign-in. The handoff is deliberately non-transferable: a sign-in link that was forwarded, or opened in another browser, cannot sign the recipient in. Start the sign-in again in the browser you want to use.

402 Payment Required

Returned when an AI action, or a placement test paid in credits, is requested but the organization does not have enough credits. The response carries the stable code insufficient_credits.

{
  "error": "Payment Required",
  "message": "You're out of AI credits. Add more to keep using the assistant.",
  "code": "insufficient_credits",
  "request_id": "req_..."
}

How to fix:

• Wait for the monthly allowance to reset, or buy a top-up pack (see AI credits)
• Related: a 429 with code usage_cap_exceeded means a short-term AI usage cap was hit; retry later

Placement tests answer 402 too, with placement_not_entitled or placement_quota_exceeded; see placement test refusals. A paid placement test past the credit balance answers insufficient_credits, and one past a spend limit answers 429 with usage_cap_exceeded; neither charges anything.

403 Forbidden

Returned when authenticated but lacking necessary permissions.

Common causes:

• API key lacks required permission
• Request IP not in allowlist
• Email account not in allowlist
• Organization access restricted
• The member is restricted to selected resources (member_access_restricted)

Example:

{
  "error": "Forbidden",
  "message": "You don't have access to this feature.",
  "code": "forbidden",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

How to fix:

• Check your API key's permissions
• Verify IP restrictions if configured
• Request additional permissions if needed

mailbox_gmail_oauth_disabled

A 403 whose code is mailbox_gmail_oauth_disabled comes from POST /emails/onboarding/oauth/start with provider: "gmail". The backend has no complete Google mailbox client credentials, or explicitly disables new Google OAuth connects through BOX_GOOGLE_OAUTH_CONNECT; GET /auth/config announces it as gmail_oauth_connect: false. Nothing about the caller's permissions is wrong. Re-authorizing an existing Gmail mailbox (POST /emails/onboarding/oauth/reauth/:id) is never refused this way.

{
  "error": "Forbidden",
  "message": "New Gmail mailboxes connect with an app password over IMAP and SMTP on this deployment, not with Google sign-in.",
  "code": "mailbox_gmail_oauth_disabled",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

How to fix:

• Connect the mailbox through POST /emails/onboarding/smtp-imap with smtp.gmail.com:465 and imap.gmail.com:993, both TLS, and a Google app password. See Gmail and Google Workspace
• An instance with its own Google app must set both BOX_GOOGLE_CLIENT_ID and BOX_GOOGLE_CLIENT_SECRET. Leave BOX_GOOGLE_OAUTH_CONNECT unset or set it to true, then enable the dashboard visibility flag on the deployments that should offer Google sign-in

looot_campaign_send_required

A 403 whose code is looot_campaign_send_required comes from POST /integrations/looot/lead-jobs, and the find_leads tool returns the same refusal as a tool error. The job named a campaign_id whose campaign mails the contacts it gets without anyone starting it: one that is active, one that finished (it restarts for new leads), or one parked because its leads were undeliverable (it resumes once they verify). Adding found leads there is sending, so it takes the right to send campaigns as well as the lead job's own: SEND_CAMPAIGNS for an API key or app, and send_campaigns for a member, including the member behind an app or the member who created the API key. A self-registered MCP client is never granted SEND_CAMPAIGNS. Nothing is started or charged. A retry with the same Idempotency-Key as a request that did start a job returns that job, even if its campaign has started sending since.

{
  "error": "Forbidden",
  "message": "This campaign is sending, so adding leads to it starts mailing them, which needs the right to send campaigns. Choose a draft or paused campaign, or leave the campaign out.",
  "code": "looot_campaign_send_required",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

How to fix:

• Pick a draft or paused campaign, then start it with POST /campaigns/:id/start once the leads are in, or leave campaign_id out and add the contacts later
• Grant the key SEND_CAMPAIGNS, or ask a member with Manage team to give the member Send campaigns. See sending campaigns

plan_offer_required

A 403 whose code is plan_offer_required comes from POST /subscription/checkout, POST /subscription/change-plan or POST /subscription/offers/:planId/checkout. Those routes sell public plans, and a private plan only to a workspace AY Inbox has offered it to. The workspace holds no open offer for the chosen plan: it was never offered, or the offer has ended or been withdrawn. The Warmup plan is sold through POST /pool-link/checkout and is refused here too.

{
  "error": "Forbidden",
  "message": "This plan is available by invitation only. Ask AY Inbox to offer it to this workspace.",
  "code": "plan_offer_required",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

How to fix:

• Pick a plan from GET /plans, or one listed by GET /subscription/offers. See plans offered to a workspace

Registration and invitation refusals

Signup and invitation refusals carry their own code, so a client can branch on the specific condition instead of matching on text. They describe the deployment's policy and never say anything about whether a given address exists.

{
  "error": "Forbidden",
  "message": "This server is invite only. Ask an administrator to invite you, then open the link in the invitation to create your account.",
  "code": "registration_invite_only",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

How to fix: on a self-hosted deployment these are configuration, not faults. See accounts and access.

Account and workspace standing

An account or workspace that support or the instance's administrators have restricted answers with its own code. These are not permission problems, and a role change does not lift them.

{
  "error": "Forbidden",
  "message": "Sending is paused for this workspace while it is under review. Contact support to resolve the review; nothing else in the workspace is affected.",
  "code": "workspace_sending_suspended",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

Confirmation required

reauth_required guards the changes that hand out a durable credential, reveal a signing secret, change who can get in, move money, cannot be undone, or reach a whole domain's mail. The full list is under actions that need a recent confirmation. List the ways the account can confirm with GET /v1/auth/reauth/methods (a passkey and a linked Google, Apple or single sign-on identity are among them; see endpoints). With a password or a current two-factor code:

curl -X POST "https://api.ayinbox.com/v1/auth/reauth" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"password": "..."}'

{ "valid_for_seconds": 300 }

The confirmation is recorded on the session and lasts for the window returned, so a run of related changes only asks once.

Turning on two-factor authentication (POST /auth/2fa/enroll/start and /confirm) is guarded too, since a confirmed authenticator is itself a way to confirm. An account with a password confirms as above. An account with neither a password nor 2FA (created through Google, Apple or single sign-on) confirms with its passkey or linked identity. One with none of those is allowed for five minutes after a sign-in like every confirmed action; an older session gets reauth_no_factor and the fix is to sign out and sign in again. API keys and OAuth tokens have no session to confirm, so these routes are reachable only with a signed-in session; that is deliberate for key creation, which otherwise lets one leaked key mint more.

{
  "error": "Forbidden",
  "message": "Confirm it is you before making this change.",
  "code": "reauth_required",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

Member access scope

A member restricted to selected resources, and any API key or OAuth app acting for one, reaches only the read routes that filter to their grants. The scope's own refusals:

A campaign or mailbox outside a restricted caller's grants answers 404, the same as one that does not exist, so a scope does not reveal what else the workspace holds. GET /unibox/thread/labels likewise returns the same 404 for an unknown thread, a thread outside the selected workspace, or a thread with no message in an accessible mailbox. An accessible thread with no labels returns an empty list.

Failure to resolve a restricted scope or its scoped counts fails the request rather than returning workspace-wide data. Realtime authorization lookup errors stop campaign, mailbox and organization channels; user-channel events whose authorization cannot be verified are withheld. See bounded realtime authorization.

{
  "error": "Forbidden",
  "message": "Your access to this workspace is limited to selected campaigns and mailboxes, and this is outside it.",
  "code": "member_access_restricted",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

How to fix: ask a member with Manage team to widen the access under Settings > Members.

slack_link_email_mismatch

A 403 whose code is slack_link_email_mismatch comes from POST /integrations/slack/link sent without a Sign in with Slack result. Confirming a Slack link that way needs the email on the Slack account's profile to be the signed-in user's AY Inbox email, compared without regard to case. The code stays usable: confirm it again with slack_code and state from POST /integrations/slack/link/verify. GET /integrations/slack/link/:code reports the check ahead of time as email_matches, and whether Sign in with Slack is available as verify_available.

{
  "error": "Forbidden",
  "message": "This Slack account's email is not the one you sign in to AY Inbox with. Continue with Slack to confirm the account is yours.",
  "code": "slack_link_email_mismatch",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

How to fix:

• Sign in to AY Inbox with the address on your Slack profile, then confirm again
• If the addresses already match, a member with manage_settings reconnects Slack under Integrations > Slack so the connection grants users:read and users:read.email

404 Not Found

Returned when the requested resource doesn't exist.

Common causes:

• Invalid resource ID
• Resource was deleted
• Resource belongs to different organization
• Typo in endpoint URL

Example:

{
  "error": "Not Found",
  "message": "Resource not found.",
  "code": "not_found",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

How to fix:

• Verify the resource ID is correct
• Check that the resource hasn't been deleted
• Ensure you're using the correct endpoint

Specific 404 codes:

409 Conflict

Returned when the request conflicts with existing data.

Common causes:

• Trying to create a resource that already exists
• Duplicate unique values
• Deleting something whose state does not allow it yet, such as an API key that can still authenticate

Example:

{
  "error": "Conflict",
  "message": "resource already exists",
  "code": "conflict",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

Creating an account for an address that already has one answers 409 with the generic conflict code and a message pointing to sign-in and password reset. With email verification on it comes from POST /auth/register/confirm, after the emailed code has shown the address is the caller's; without it, POST /auth/register answers it directly.

A few conflicts carry their own code. The mailbox import's are under mailbox import refusals. A contact's email address has to be free, so changing one to an address another contact already holds is refused rather than merging the two:

mailbox_cloud_unenroll_failed is a self-hosted instance losing contact with AY Inbox Cloud mid-delete. Deleting an enrolled mailbox has to revoke its enrollment before the record goes, because the pool holds the mailbox's own SMTP/IMAP credentials and that record is the only thing that knows the enrollment exists. The same call releases a cloud-managed mirror before the record goes, so the mailbox returns to the cloud workspace and can be adopted again instead of staying claimed by an instance that no longer keeps it. The mailbox record remains. AY Inbox attempts to restore it onto its worker immediately, and the worker reconciler may restore it later if that attempt fails. Retry the delete once the instance can reach the cloud again. Unenrolling under Settings > AY Inbox Cloud first does not help: it makes the same call.

422 Unprocessable

Returned when validation fails on the request data.

Common causes:

• Invalid email format
• String exceeds maximum length
• Number outside valid range
• Invalid enum value

Example:

{
  "error": "Unprocessable",
  "message": "validation failed",
  "code": "unprocessable",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

500 Internal Server Error

Returned when an unexpected error occurs on the server.

Example:

{
  "error": "Internal Server Error",
  "message": "Something went wrong.",
  "code": "internal_error",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

How to fix:

• Retry the request after a short delay
• If persistent, contact support with request details

A 500 always carries this same message. The underlying detail is not returned, because it is usually database or provider output naming tables, columns and hosts, none of which helps a caller. It is logged against the request_id in the response, so quoting that id in a support request is what connects the two.

One internal_error variant is worth distinguishing. When an authentication endpoint cannot send its email, the message names that specifically rather than reporting a generic fault, because on a self-hosted instance the person reading it is often the one who can fix it:

{
  "error": "Internal Server Error",
  "message": "We couldn't send the email. If you administer this server, check the mail transport configuration.",
  "code": "internal_error",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

On a self-hosted deployment that means MAIL_TRANSPORT and the SMTP_ variables. See self-hosting.

503 Service Unavailable

Returned when the service is temporarily unavailable.

Every endpoint that checks a password, an emailed or two-factor code, or a sign-in link charges an attempt to its budget before it compares anything. When that budget cannot be read, the request is refused with code: "attempt_check_unavailable" and a Retry-After header, nothing is compared and the attempt is not counted, so a sign-in can briefly fail during a cache outage. Retry after the header. Looking up a CLI or AY Inbox Cloud pairing code (/auth/cli/codes/:code, /pool-link/codes/:code) answers the same code when its lookup budget cannot be read.

{
  "error": "Service Unavailable",
  "message": "We couldn't check this attempt right now, so it was not counted. Wait a few seconds and try again.",
  "code": "attempt_check_unavailable",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

Other temporary failures answer the generic form:

Example:

{
  "error": "Service Unavailable",
  "message": "service unavailable",
  "code": "service_unavailable",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

How to fix:

• Wait and retry with exponential backoff
• Check status page for incidents

mailbox_provider_not_configured

A 503 whose code is mailbox_provider_not_configured is not transient and retrying will not help. It means the deployment has no OAuth client for the mailbox provider the request asked for, which only happens on a self-hosted install.

{
  "error": "Service Unavailable",
  "message": "Gmail is not configured on this deployment. Set BOX_GOOGLE_CLIENT_ID and BOX_GOOGLE_CLIENT_SECRET in your .env, then restart.",
  "code": "mailbox_provider_not_configured",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

How to fix:

• Set BOX_GOOGLE_CLIENT_ID and BOX_GOOGLE_CLIENT_SECRET, or BOX_OUTLOOK_CLIENT_ID and BOX_OUTLOOK_CLIENT_SECRET, in the .env at your install root, then restart
• Or connect the mailbox over SMTP and IMAP instead, which needs no configuration
• Full walkthrough: connect mailboxes

ai_not_configured

A 503 whose code is ai_not_configured is not transient and retrying will not help. It comes from POST /templates/analyze and means the deployment has no AI provider set up at all. It is how a client tells "there is no AI here" apart from "the provider is having a bad minute", which returns the generic service_unavailable and is worth retrying.

{
  "error": "Service Unavailable",
  "message": "AI analysis is not configured on this deployment.",
  "code": "ai_not_configured",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

How to fix:

• Set AI_PROVIDER and AI_API_KEY in the .env at your install root, then restart. See the configuration reference
• Hide the AI affordance in your client rather than retrying: nothing about the request will make it succeed

slack_not_configured

A 503 whose code is slack_not_configured is not transient and retrying will not help. The instance is not set up for Slack, which only happens on a self-hosted install. The three Slack request URLs (/api/v1/integrations/slack/events, /interactivity and /commands) answer it whenever SLACK_SIGNING_SECRET is unset.

{
  "error": "Service Unavailable",
  "message": "Slack is not set up on this AY Inbox instance.",
  "code": "slack_not_configured",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

How to fix:

• Create the instance's Slack app and set SLACK_OAUTH_CLIENT_ID, SLACK_OAUTH_CLIENT_SECRET and SLACK_SIGNING_SECRET on the backend and the consumer, then restart. See Slack app
• In a client, read app_configured and interactive_configured from GET /integrations/slack/status and hide the Slack affordances rather than retrying

Those request URLs answer 401 unauthorized to a request whose Slack signature does not verify. Linking a Slack account to a workspace you are not a member of is 403 forbidden, and linking one whose email is not yours without signing in to it with Slack is 403 slack_link_email_mismatch.

mailbox_allowance_reached

A 403 whose code is mailbox_allowance_reached comes from every path that connects a mailbox: POST /emails/onboarding/oauth/start, POST /emails/onboarding/oauth/finish, POST /emails/onboarding/smtp-imap, and per row inside POST /emails/onboarding/smtp-imap/bulk. A mailbox import does not answer it over HTTP: the rows past the allowance fail with the cause allowance_reached and can be retried once it is raised. It is not a permission problem: the workspace holds its whole mailbox allowance, which on a paid plan is one mailbox for every send a day the plan includes, and 10 on a free workspace. Nothing was connected.

{
  "error": "Forbidden",
  "message": "This workspace holds 15000 of its 15000 mailboxes. Request an increase, or move to a plan with more daily sends.",
  "code": "mailbox_allowance_reached",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

How to fix:

• Read GET /emails/allowance first: remaining says how many connects will succeed, and pending_request whether an increase is already asked for
• Submit a limit-increase request for max_email_accounts via POST /organization/:orgId/limit-requests, or move to a plan with more daily sends. An approved request raises the allowance immediately; retry the connect then
• Reconnecting an existing mailbox never returns this code

storage_limit_reached

A 400 whose code is storage_limit_reached comes from POST /campaigns/:id/attachments, from POST /email-images, and from a campaign duplicate that would copy attachments. The workspace's stored bytes, its attachments across every campaign plus its email image library, would pass the quota. The check and the write happen together under one per-workspace lock shared by both, so two uploads racing for the last of the quota cannot both get in. Nothing was stored.

{
  "error": "Bad Request",
  "message": "Storage limit reached: 51190 MB of 51200 MB used, 12 MB to add. Remove attachments or images, or upgrade your plan.",
  "code": "storage_limit_reached",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

How to fix:

• GET /organization/current/limits reports storage.used_bytes and storage.limit_bytes, and storage.over_quota when a plan change left the workspace above the quota. Existing attachments keep sending either way
• Delete attachments you no longer need (DELETE /campaigns/:id/attachments/:attachmentId) or images (DELETE /email-images/:id), or move to a paid plan for the larger quota

mailbox_validation_timeout

A 400 whose code is mailbox_validation_timeout comes from the SMTP and IMAP connect and re-authorize endpoints. AY Inbox proves credentials by opening a real connection to the mail server before it stores anything, and a connection stayed silent inside that window. The message names the leg that did not answer and says whether the other one signed in. Nothing was saved and no mailbox was created.

{
  "error": "Bad Request",
  "message": "SMTP (smtp.gmail.com:465) did not answer in time. IMAP (imap.gmail.com:993) signed in. Nothing was saved. Check the host and port, then try again. Port 465 did not answer and the worker could not use 587 with STARTTLS on the same server either. Some networks block outbound mail ports; check that the server is reachable from outside and which port it listens on.",
  "code": "mailbox_validation_timeout",
  "request_id": "6f3c0a1e-2d47-4c6b-9a1f-2b7c5f0e8d31"
}

The same code with a message that begins AY Inbox's worker did not report back means no worker answered the check at all, so the mail server was never tested. The check is offered to each healthy worker in turn and waits on at most two that take it without answering, so this means the fleet as a whole is not answering. On the hosted product, retry and contact support if it persists. On a self-hosted instance, check that a worker is running, heartbeating, and reaching the same Redis as the backend: the check reaches the worker over Redis and its answer comes back the same way.

How to fix:

• Read which leg stayed silent. One leg passing and the other hanging is the network between the worker and that port, not the password: a port that nothing listens on, or that a firewall drops, takes the full timeout rather than refusing straight away
• When 465 never answers, the worker also tries 587 with STARTTLS on the same server and uses it if it connects; a passing check is then stored with port 587. This error means neither port answered, so check that the server is reachable from outside your network and which port it listens on
• Retry. A mail server under load can be slow once and answer immediately on the next attempt
• Confirm the server accepts connections from outside your network, and that the security setting matches the port: tls for 465 and 993, starttls for 587 and 143

mailbox_auth_refused

A 400 whose code is mailbox_auth_refused comes from the SMTP and IMAP connect and re-authorize endpoints. The mail server answered and refused the sign-in. The message names the leg and the server, quotes the server's own reply, and for Google's servers says what an app password is. Nothing was saved.

{
  "error": "Bad Request",
  "message": "SMTP (smtp.gmail.com:587) refused the sign-in: 535 5.7.8 Username and Password not accepted. IMAP (imap.gmail.com:993) refused the sign-in: imap: NO [AUTHENTICATIONFAILED] Invalid credentials (Failure). Nothing was saved. Google itself refused this address and password. Use a 16-letter app password from myaccount.google.com/apppasswords, created while signed in to the Google account that owns this address, and enter the account's own sign-in address rather than an alias or a group. A deleted app password stops working at once, and on Google Workspace the administrator can block app passwords or IMAP.",
  "code": "mailbox_auth_refused",
  "request_id": "6f3c0a1e-2d47-4c6b-9a1f-2b7c5f0e8d31"
}

How to fix:

• Read the server's reply in the message: it says which leg refused and usually why (a wrong password, an app password required, IMAP switched off for the domain)
• The username is normally the full address. The password is the provider's app password when the account has two-step verification on, never the account password
• Whitespace is not the problem: AY Inbox trims the password on every path, and removes every space from one bound for a Google server
• On Google, a refusal with a real app password nearly always means the address is not the account that issued it: enter the account's own sign-in address rather than an alias or a group, create the app password while signed in to that account, and check it has not been deleted since. On Google Workspace the administrator can also block app passwords or IMAP for the organization

mailbox_unreachable

A 400 whose code is mailbox_unreachable comes from the same endpoints. The worker could not open a connection to the server at all: the name did not resolve, the port refused, a firewall dropped the packets, or the host name points to a private network address. The message says which server and which of those it was. Nothing was saved.

{
  "error": "Bad Request",
  "message": "SMTP (smtp.example.com:465) could not be reached from the worker: the port refused the connection. Nothing was saved.",
  "code": "mailbox_unreachable",
  "request_id": "6f3c0a1e-2d47-4c6b-9a1f-2b7c5f0e8d31"
}

How to fix:

• Check the host and port for typos
• The connection leaves from the worker, not from your browser or from the API host: the worker's network has to reach the server on that port. Some hosting providers block outbound mail ports until asked
• A host name that points to a private network address (such as 10.x, 192.168.x or a loopback address) is refused, because AY Inbox only connects mailboxes to public addresses. Use the host name your provider gives for connecting from outside your network. On a self-hosted instance, the message also names MAIL_ALLOW_PRIVATE_HOSTS=true, which the operator can set to connect mail servers on a private network (see configuration)

mailbox_tls_failed

A 400 whose code is mailbox_tls_failed comes from the same endpoints. The server was reached but no secure connection could be made: the certificate did not verify for that host name, the handshake failed, or the port expects a different mode (tls on a STARTTLS port, or the reverse) and no STARTTLS was offered. Nothing was saved.

{
  "error": "Bad Request",
  "message": "IMAP (mail.example.com:143) did not complete a secure connection: the server offers no STARTTLS on this port, and AY Inbox only signs in over an encrypted connection. Use the server's SSL/TLS port (usually 993) or a port that offers STARTTLS (usually 143). Nothing was saved.",
  "code": "mailbox_tls_failed",
  "request_id": "6f3c0a1e-2d47-4c6b-9a1f-2b7c5f0e8d31"
}

When the certificate is what failed, the message says why (issued for a different host name, expired, or not vouched for by a recognised certificate authority) and names the certificate the server presented: who it is for, who issued it (or that it is self-signed) and the SHA-256 fingerprint of its public key. When the server can be trusted on its own certificate instead, the message ends by saying so and the response carries "reason": "certificate_untrusted"; the dashboard's connect and reconnect forms then offer Trust this server's own certificate.

How to fix:

• Match the security setting to the port: tls for 465 and 993, starttls for 587 and 143, unless the provider documents otherwise
• Use the host name the certificate is issued for, which is the one in the provider's documentation rather than an alias or an IP address
• For a server with a self-signed or company certificate, compare the fingerprint with the one the server's owner gives you, then connect again with tls_unverified: true on that server (in the dashboard, Trust this server's own certificate). The mailbox is then trusted on that certificate only. See servers with their own certificate

Mailbox errors TLS_CERTIFICATE_CHANGED and TLS_CERTIFICATE_UNCONFIRMED

These are not responses to a request. They are the error a connected SMTP/IMAP mailbox reports (in the mailbox drawer, GET /analytics/accounts/:id, and the EMAIL_SERVER_ERROR notification) when it trusts a server on its own certificate and AY Inbox did not connect:

Both are warnings: the mailbox is not deactivated, its credentials are not marked invalid, and nothing it was due to send or sync is dropped. It retries on its usual interval.

How to fix:

• Check with the server's owner that the change is expected
• Open Settings > Server certificates on the mailbox and choose Re-confirm, or call POST /emails/onboarding/smtp-imap/:id/certificates/check and then .../certificates/confirm with the fingerprints it reported. The error clears once the confirmed certificates connect
• If the confirm call answers mailbox_tls_failed saying the server did not present the certificate with the fingerprint you confirmed, a fingerprint was mistyped or the certificate changed after the check. Nothing was changed; run the check again and confirm what it reports

mailbox_server_declined

A 400 whose code is mailbox_server_declined comes from the same endpoints. The sign-in could not be completed for a reason other than the credentials: the server asked for a retry later (a 4xx reply, often a login rate limit), it offers no sign-in method AY Inbox implements, it answered with a 5xx that is not about the password (a mechanism it does not support, a STARTTLS it insists on), it only offers sign-in without encryption, the conversation broke, or the probe itself failed before a reply arrived. The message carries the server's reply when there is one. Nothing was saved.

{
  "error": "Bad Request",
  "message": "SMTP (smtp.example.com:587) declined the sign-in for now and asks for a retry: 454 4.7.0 Too many login attempts, please try again later. Nothing was saved.",
  "code": "mailbox_server_declined",
  "request_id": "6f3c0a1e-2d47-4c6b-9a1f-2b7c5f0e8d31"
}

How to fix:

• For a 4xx reply, wait a few minutes and retry
• For a server that offers only mechanisms AY Inbox does not implement (NTLM, GSSAPI, XOAUTH2), use the provider's documented SMTP submission host, which normally offers LOGIN or PLAIN; a different password does not add a mechanism. The message lists what the server offered
• A server that only offers sign-in over an unencrypted connection is refused before any password is sent. Use its SSL/TLS port (usually 465) or a port that offers STARTTLS (usually 587)

mailbox_worker_unreachable

A 503 whose code is mailbox_worker_unreachable comes from DELETE /emails/{id}. Disconnecting a mailbox has to reach the machine that syncs it before the record goes, because once the record is gone nothing can tell that machine to stop. When the instruction cannot be delivered, nothing is removed and the mailbox is left exactly as it was.

{
  "error": "Service Unavailable",
  "message": "This mailbox could not be disconnected right now because the machine syncing it could not be reached. Nothing was removed, so try again in a moment.",
  "code": "mailbox_worker_unreachable",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

How to fix:

• Retry the delete. It is safe to repeat: a mailbox that is already gone returns 404, and one that is still there is untouched

mailbox_send_as_unsupported

A 400 whose code is mailbox_send_as_unsupported comes from POST /emails/{id}/identity/refresh and from a PATCH /emails/{id} that sets send_as_email. Only Gmail and Google Workspace mailboxes publish the addresses they are allowed to send as; an Outlook or SMTP/IMAP mailbox has no such list, so there is nothing to refresh and nothing to choose from.

{
  "error": "Bad Request",
  "message": "This mailbox's provider does not expose send-as addresses. Only Gmail and Google Workspace mailboxes do.",
  "code": "mailbox_send_as_unsupported",
  "request_id": "9f0a6f21-2c7e-4f2d-9d0e-1f7b9a2c4e55"
}

How to fix:

• Read GET /emails/{id}/identity first. Its supported field is false for these mailboxes, and identities is empty
• Send from the mailbox's own address, which is what an empty send_as_email means

mailbox_send_as_unknown

A 400 whose code is mailbox_send_as_unknown comes from a PATCH /emails/{id} that sets send_as_email to an address the provider has not verified for that mailbox. The choice is refused here rather than at send time, where the provider's own refusal arrives days later against a campaign step and names nothing you could act on.

{
  "error": "Bad Request",
  "message": "That address is not one your provider has verified this mailbox to send as. Refresh the list, or add and verify the address in your provider first.",
  "code": "mailbox_send_as_unknown",
  "request_id": "b71c3f88-0b3e-4a41-9a52-2f4f1fd0c0aa"
}

How to fix:

• Add the alias in Gmail (Settings, Accounts, "Send mail as") and finish its verification
• Call POST /emails/{id}/identity/refresh so AY Inbox re-reads the list, then set send_as_email to an address whose verified is true

mailbox_signature_too_large

A 400 whose code is mailbox_signature_too_large comes from POST /emails/{id}/identity/refresh with import_signature set. The provider's signature is larger than AY Inbox stores (20000 characters of HTML), and it is refused rather than truncated: half a signature is worse than none. The send-as list is not stored either, so the call changes nothing.

{
  "error": "Bad Request",
  "message": "The signature on this mailbox is larger than AY Inbox stores (20000 characters). Shorten it in your provider and import it again.",
  "code": "mailbox_signature_too_large",
  "request_id": "2d5e9a13-7c41-4f9b-bb17-a0f1d9c6e332"
}

How to fix:

• Shorten the signature in Gmail, usually by linking an image rather than embedding it, and import again
• Or write the signature in AY Inbox directly with PATCH /emails/{id}

mailbox_identity_unavailable

A 503 whose code is mailbox_identity_unavailable comes from POST /emails/{id}/identity/refresh. Reading a mailbox's sending addresses is an account operation, so it runs on the worker holding that mailbox, never from the API itself. It is unavailable exactly when that machine is: while the mailbox is being moved between workers, just after a worker restart, or before a newly connected mailbox has been placed. Nothing was changed.

{
  "error": "Service Unavailable",
  "message": "AY Inbox could not reach the machine running this mailbox, so its sending addresses were not refreshed. Nothing was changed; try again in a moment.",
  "code": "mailbox_identity_unavailable",
  "request_id": "6e2f1a90-5d13-4a77-9c0b-73f0b5a2e118"
}

How to fix:

• Retry. Placement happens within moments, so a second attempt usually succeeds
• GET /emails/{id} reports the mailbox's status; an inactive mailbox is not placed on a worker at all and will keep refusing until it is reactivated

Error handling best practices

Implement retry logic

For transient errors (5xx, 429), implement exponential backoff:

async function requestWithRetry(url, options, maxRetries = 3) {
  const backoff = (attempt) =>
    new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));

  for (let attempt = 0; ; attempt++) {
    let response;
    try {
      response = await fetch(url, options);
    } catch (networkError) {
      if (attempt === maxRetries - 1) throw networkError;
      await backoff(attempt);
      continue;
    }

    if (response.ok) {
      return response.json();
    }

    // Retry server errors and rate limits; every other 4xx is final
    const retryable = response.status === 429 || response.status >= 500;
    if (retryable && attempt < maxRetries - 1) {
      await backoff(attempt);
      continue;
    }

    // Carry the machine-readable code, e.g. idempotency_outcome_unknown
    const body = await response.json().catch(() => ({}));
    const error = new Error(body.message || `HTTP ${response.status}`);
    error.status = response.status;
    error.code = body.code;
    throw error;
  }
}

A retry of a write that carries an Idempotency-Key answers with whatever the first attempt recorded. A 429 leaves the key as it was, so the same key runs the request unless an earlier attempt already recorded an outcome. A 5xx from a request that reached the operation makes the same key answer 409 idempotency_outcome_unknown instead of running it again; a 5xx from a gateway the request never got past leaves the key unused, so the retry runs it for the first time. On idempotency_outcome_unknown, stop retrying and use a new key only once you have established that the change did not happen. See retry safety.

Parse error responses

Always parse and handle error responses:

async function apiRequest(url, options) {
  const response = await fetch(url, options);

  if (!response.ok) {
    const error = await response.json();
    throw new ApiError(response.status, error.error, error.message);
  }

  return response.json();
}

class ApiError extends Error {
  constructor(status, type, message) {
    super(message);
    this.status = status;
    this.type = type;
  }
}

Rate limiting

When you exceed rate limits, you'll receive:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 60 seconds.",
  "code": "rate_limit_exceeded",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

Use the Retry-After header to determine when to retry.

Looking up a CLI or AY Inbox Cloud pairing code is budgeted per signed-in person, and past it answers 429 with code: "code_lookup_limited" and Retry-After: 60. Check the code shown on the other device before trying again.

Admin device request errors

The admin device flow adds admin_device_expired (404, indistinguishable invalid/unknown/expired/ consumed request), admin_device_resolved (409, already decided or mismatched/ replayed consent), and admin_device_slow_down (429, poll faster than five seconds). Start again on expiry and never auto-approve on conflict. Attempt budgets use existing rate_limit_exceeded. Auth/MFA/reauth and dependency failures keep existing codes. Redis failures never authorize a single-factor or anonymous admin. Node diagnostics use generic errors and explicit unavailable/stale coverage, not outage inference.

Admin send hold errors

POST /admin/sends/holds/:id/resolve adds three codes:

Agent sign-up errors

POST /agents/register answers these. Nothing is created when any of them is returned.

POST /agents/claim answers these. Nothing changes and the agent's key keeps working when any of them is returned.

See also

• Authentication
• Endpoints