Errors

Every AI Inbx error code in the problem+json body, what each one means, how to recover from it, and which failures are worth retrying.

Every failure answers with application/problem+json (RFC 9457):

{
  "type": "https://docs.aiinbx.com/problems/invalid_request",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "Request body is invalid",
  "code": "invalid_request",
  "request_id": "8f2c4a1b-...",
  "issues": [
    { "path": "to.0", "message": "Invalid email address" },
    {
      "path": "subject",
      "message": "String must contain at most 998 character(s)"
    }
  ]
}

Handling them

import { APIError, NotFoundError, RateLimitError } from "aiinbx"

try {
  await aiinbx.emails.send(payload)
} catch (error) {
  if (error instanceof NotFoundError) return null
  if (error instanceof RateLimitError) return scheduleRetry()

  if (error instanceof APIError) {
    console.error(error.status, error.code, error.requestId)
    if (error.code === "invalid_request") {
      console.error(error.body.issues)
    }
  }

  throw error
}

from aiinbx import APIStatusError

try:
    client.emails.send(payload)
except APIStatusError as error:
    print(error.status_code, error.request_id)
    print(error.body["code"], error.body.get("issues"))

Retry or not

Both SDKs already retry 429 twice, and network failures, 408, 409 and 5xx twice when the retry cannot act twice — a GET, PUT or DELETE, or a request with an idempotency key — with bounded exponential backoff, honoring Retry-After. Tune with maxRetries / max_retries.

Codes

Grouped by what actually went wrong.

Authentication and authorization

unauthorized

401 — no Authorization header, a malformed one, or a deleted key. The response carries WWW-Authenticate: Bearer. Check that the key is being read from the environment and hasn’t been deleted. See Authentication.

forbidden

403 — the key is valid but its scope doesn’t cover this operation. A read key can’t send; a sending key can’t change configuration. Retrying won’t help; use a key with the right scope.

workspace_required

400 — an access token from a CLI or MCP sign-in reaches several workspaces and the request named none. Send AIInbx-Workspace with an id from GET /workspaces. API keys belong to one workspace and never see this.

shared_apps_disabled

403 — mailboxes.connect was called without an app_id. Connecting without one isn’t available: register your own OAuth app and pass its ID.

Plan and allowances

plan_required

402 — the workspace has no plan, and a workspace without one can’t send or create anything: domains, mailboxes, pacing rules, API keys, spaces, webhook endpoints, OAuth apps. Receiving is not affected. Choose one in the console’s billing settings. Retrying won’t help until then.

allowance_reached

402 — the plan’s allowance for this is used up; detail says which. Emails are counted per month: upgrade, turn on extra usage in billing settings, or wait for the month to turn. Custom domains, mailboxes and active custom pacing rules are counted as held: delete a domain, disconnect a mailbox or disable a rule to free one, or upgrade. Subdomains under a wildcard, the provided domain and its ceilings are never counted, and reconnecting a mailbox that is active or needs_reauth takes nothing new.

Request format

unsupported_media_type

415 — an operation that accepts a JSON body was called without Content-Type: application/json. Bodyless operations do not require this header.

invalid_json

400 — the Content-Type said JSON but the body didn’t parse. Usually truncation or a stray trailing comma.

invalid_request

422 — the body parsed but failed validation. issues names each offending field with a path and a message. Also 400 from a few operations that validate outside the body schema.

invalid_query

400 — a query parameter was rejected: an out-of-range limit, an unknown status, a malformed address filter. issues names the parameter.

invalid_cursor

400 — the cursor isn’t a cursor this endpoint issued. Cursors aren’t portable between endpoints; use the next_cursor from the same list. See Pagination.

invalid_thread_id

400 — the thread_id isn’t a well-formed thread ID (thr_ plus 32 hex characters).

invalid_idempotency_key

400 — the Idempotency-Key header is empty or longer than 255 characters.

method_not_allowed

405 — the path exists but not for this HTTP method.

no_body

400 — a request that requires a body arrived without one.

Content

no_recipients

400 — to is empty.

recipients_suppressed

400 — every to address is suppressed, so there is nobody left to send to. On a partial send the response’s suppressed array tells the same story less severely. An invitation to a suppressed address fails the same way, and nothing is created. Retrying will not help.

sender_unknown

400 — the from address is on no domain and no connected mailbox of the workspace. Add its domain, or connect the mailbox and check it’s active. A domain the workspace has but hasn’t verified gets domain_unverified instead. It also comes when the address now belongs to another space than the one the send is held to — an agent inbox, or mail scheduled before its domain moved.

tracking_unavailable

400 — the send asked for tracking.opens or tracking.clicks from a connected mailbox. Only mail sent from a domain is tracked; drop tracking, or set both to false.

too_many_recipients

400 — more than 100 addresses in to, cc, bcc, or reply_to. Split the send.

unsubscribe_single_recipient

400 — a send marked unsubscribe: true has more than one recipient across to, cc and bcc. The unsubscribe link is personal; send one message per recipient.

attachments_too_large

413 — the attachments given in one request decode to more than 3 MB in total, or, on PATCH /emails/{id}, the files the email would carry come to more than 7 MB together. Large files belong behind a link. (More than 20 attachments is invalid_request.)

State conflicts

not_found

404 — no such resource in this workspace. Also what you get for an ID of the wrong type, since IDs are type-tagged, and for a space_id or space that names no space of the workspace.

thread_not_found

404 — the thread doesn’t exist or isn’t yours. Check the thread_id came from this workspace.

thread_empty

409 — a forward was asked of a thread with nothing sent or received on it yet — only scheduled or canceled messages. There is nothing to forward until a message has left or arrived.

not_prepared

404 — the attachment has no prepared text. Either its type is unsupported, extraction failed, or preparation hasn’t finished. The original is still downloadable — see Attachments.

not_scheduled

409 — cancel or PATCH /emails/{id} was called on a message that is neither scheduled nor a draft any more. It has already begun sending, or was canceled or discarded. See Scheduling and Drafts.

not_draft

409 — POST /emails/{id}/send was called on a message that isn’t a draft — it was sent already, or discarded. See Drafts.

attachment_not_found

422 — an edit kept an attachment, by { id }, that isn’t one of this email’s. Keep only ids from the email’s own attachments.

unsubscribe_recipient_fixed

409 — an edit changed the recipients of an unsubscribable email. Its unsubscribe link was made for the one recipient it was written to; send anyone else a new email.

idempotency_key_reused

409 — this Idempotency-Key was used with a different body. Either the key is being reused across genuinely different sends, or the body isn’t as deterministic as you think (a timestamp in the subject will do it). See Idempotency.

domain_unverified

409 — the from address is on a domain of the workspace whose DKIM identity isn’t verified, or has lost verification. The message names the domain. Run domains.verify, then domains.diagnostics to see which records are missing and what else in the zone is in the way. A scheduled or queued email whose domain loses verification before it leaves fails, with the same message on its timeline. See Domains.

domain_taken

409 — the space already has this domain (or the workspace, for a domain without a space_id). saas.com and *.saas.com are one identity, so either one takes the other. Another space or workspace having the name is not an error: whoever’s DKIM record DNS carries sends as it — see Moving a domain.

reserved_subdomain

409 — the name is bounces. under a wildcard, which is where that wildcard’s return path lives. Pick another label.

reserved_domain

409 — the name is under aiinbx.app. Every workspace is given one name there, <slug>.aiinbx.app, and nobody adds another — see Your provided domain.

domain_platform

409 — the domain is the one the platform sends its own mail from, and cannot be deleted. Only ever seen by the platform’s own workspace.

domain_provided

409 — the domain is the one the workspace was given. It came with the workspace and cannot be deleted; it goes when the workspace does.

rule_builtin

409 — the pacing rule came with the workspace. The provided domain’s ceilings cannot be changed, switched off or deleted.

slug_taken

409 — the slug is claimed. OAuth app slugs are globally unique because they form the hosted connect URL; workspace slugs because they form the console URL. Pick another one.

external_id_taken

409 — another space in the workspace already has that external_id. One space per customer is the point of the field; find the existing one with GET /spaces?external_id=. See Spaces.

mailbox_inactive

409 — the mailbox isn’t active. Check its state: needs_reauth means the customer has to reconnect, disconnected means it’s gone. See Mailboxes.

mailbox_space_conflict

409 — the mailbox can’t be connected in this space. Either it is already connected in another space (a mailbox’s space is fixed when it is first connected, so reconnect it through a URL minted for that space), or its address is on a domain verified in another space, which decides the address’s space — connect it there. See One address, one space.

invalid_domain

400 — the domain name isn’t a valid registrable domain.

invalid_webhook_url

400 — a webhook endpoint url isn’t one events can be sent to: not an absolute URL, not https, carrying credentials, on a port other than 443, or resolving to anything but public addresses (localhost, loopback, private and link-local ranges are refused). detail says which.

unknown_region

400 — region isn’t one of eu-central-1 or us-east-1.

region_fixed

409 — the domain is verified, or is a subdomain, and its region no longer moves. A verified domain changes region by being deleted and added again; a subdomain is handled wherever its wildcard is. See Regions.

OAuth flow

invalid_state

400 — the OAuth callback’s state parameter didn’t validate. Usually a link opened out of context; start the connect flow again.

expired_state

400 — the connection URL expired, was already used, or was never one of ours. They’re short-lived and single-use: good for ten minutes, spent when the person approves — redirect the customer, don’t email them the link. Answered as JSON on our callback page rather than on return_to, which went with the state.

invalid_tenant

400 — the Microsoft tenant on the OAuth app doesn’t match the account that authorized. Check the tenant restriction.

invalid_return_url

400 — a return_urls entry on an OAuth app isn’t one a connect link could return to: not an absolute URL, not https (plain http is allowed on localhost), carrying credentials, or carrying a #fragment. At most 20 per app.

return_url_not_registered

400 — a connect link was opened with a return_to the app hasn’t registered. Add it to the app’s return_urls — matched on origin and path, so one entry covers every query string. The server-side mailboxes.connect call isn’t held to the list, since it’s authenticated.

connect_unavailable

503 — the store that holds a connection URL’s state while the person is at the provider isn’t answering, so mailboxes.connect, a connect link or the callback can’t go on. Nothing was spent; retry with backoff, or send the person through the flow again.

Upstream and server

too_many_requests

429 — the workspace’s request budget is spent, too much of it is in flight, or the platform is at capacity; detail says which. The response carries Retry-After in seconds and the RateLimit-* headers. Wait that long and retry — both SDKs do so automatically. Sustained 429s mean the integration is faster than the budget: pace it from RateLimit-Remaining, or ask for a larger budget.

rate_limited

429 — an upstream mail provider is throttling. Not the workspace’s budget: that is too_many_requests. The response carries Retry-After in seconds. Wait that long and retry — both SDKs do so automatically.

send_failed

502 — the provider rejected the message at hand-off. detail carries what it said. Retryable, but if it repeats for the same message the content or sender is the problem.

provider_error

502 — a mail provider (Gmail, Microsoft Graph, the sending backend) failed. Retry with backoff.

internal_error

500 — something broke on our side. The request_id is already logged; quote it if it persists. Retry with backoff.

Debugging