Errors and troubleshooting

Errors are JSON with a name, a machine-readable code, a message and often a fix. Match on code, not on message.

{ "name": "MessageRejectedError", "code": "inbox_paused", "message": "Inbox is paused and cannot send", "fix": "Set the inbox status to active" }

Validation errors (400, code validation_error) add errors: a list of { path, message }. Plan limit errors (402) add errors[0] with limit, current, max and the plan that allows more. Every response carries an x-request-id header; quote it when you ask for help. 429 responses carry Retry-After.

Every error code#

The list below is checked against the server's source on every test run, so a code cannot be added without being documented here.

Errors from /v0 and the hosted MCP endpoint

Errors from the dashboard's session endpoints (/auth)

Errors on operator-only routes; you will not normally see these

Recorded examples#

These bodies were recorded from the running server.

400 validation_error

{
  "name": "ValidationError",
  "code": "validation_error",
  "message": "Request validation failed",
  "errors": [
    {
      "path": [
        "username"
      ],
      "message": "Expected string, received number"
    }
  ]
}

400 validation_error

{
  "name": "ValidationError",
  "code": "validation_error",
  "message": "At least one recipient is required",
  "errors": [
    {
      "path": [
        "to"
      ],
      "message": "at least one of to, cc or bcc is required"
    }
  ]
}

401 unauthorized

{
  "name": "AuthenticationError",
  "code": "unauthorized",
  "message": "Missing or invalid API key",
  "fix": "Send 'Authorization: Bearer <api_key>'"
}

403 missing_permission

{
  "name": "ForbiddenError",
  "code": "missing_permission",
  "message": "API key lacks permission: webhook_create"
}

403 email_unverified

{
  "name": "ForbiddenError",
  "code": "email_unverified",
  "message": "Verify your email address before sending mail or creating API keys",
  "fix": "Click the link in the verification email, or POST /auth/resend-verification"
}

404 not_found

{
  "name": "NotFoundError",
  "code": "not_found",
  "message": "Inbox not found"
}

402 plan_limit_exceeded

{
  "name": "PlanLimitError",
  "code": "plan_limit_exceeded",
  "message": "Free plan limit reached: inboxes (3/3)",
  "fix": "Upgrade to the Pro plan via POST /v0/billing/checkout (plan: \"pro\")",
  "errors": [
    {
      "limit": "inboxes",
      "current": 3,
      "max": 3,
      "plan": "free",
      "upgrade_to": "pro"
    }
  ]
}

422 recipient_suppressed

{
  "name": "UnprocessableError",
  "code": "recipient_suppressed",
  "message": "Recipient(s) suppressed after a bounce or complaint: gone@example.org",
  "fix": "Remove the address(es) with DELETE /v0/suppressions/{address} or send to a different recipient"
}

409 pod_not_empty

{
  "name": "ConflictError",
  "code": "pod_not_empty",
  "message": "Pod still has 1 inbox(es); delete them first",
  "fix": "Delete all inboxes in the pod"
}

400 invalid_webhook_url

{
  "name": "ValidationError",
  "code": "invalid_webhook_url",
  "message": "Webhook url must be a public https URL"
}

400 validation_error

{
  "name": "ValidationError",
  "code": "validation_error",
  "message": "range plus window divided by period must not exceed 1000 buckets"
}

422 reserved_username

{
  "name": "ValidationError",
  "code": "reserved_username",
  "message": "The username \"admin\" is reserved",
  "fix": "Choose a different username"
}

Troubleshooting#

401 unauthorized on every call. The header must be Authorization: Bearer am_... with the whole key. A key that was deleted, or whose scoped inbox was deleted, answers 401. A key in the ?api_key= query is accepted on /v0 routes for the benefit of browsers opening WebSockets, but URLs end up in proxy logs, so use the header everywhere else. The hosted MCP endpoint accepts the header only.

403 email_unverified when sending or creating a key. The owner email is not verified. Open the link in the verification email. Receiving works before that.

400 bad_request "Body cannot be empty when content-type is set to 'application/json'". You sent Content-Type: application/json on a request with no body, usually a DELETE or a body-less POST. Drop the header, or send {} on a POST. The SDKs do this for you.

404 not_found for something that exists. The resource is outside your key's scope (the API does not reveal that), or the inbox id in the path is wrong. Check that you are using a key for the right pod or inbox.

403 missing_permission. The message names the permission. Create a key that includes it, or an organization-level key without a list. Scoped keys also cannot create pods or inboxes.

402 plan_limit_exceeded. Read errors[0]: it names the limit and the plan that allows more. Delete unused inboxes or webhooks, or upgrade.

403 recipient_blocked. A block list matched, or a send allow list exists and the recipient is not on it. Lists are checked at inbox, pod, then organization scope; the first scope with a matching entry decides.

422 recipient_suppressed. The address bounced or complained before. Remove it with DELETE /v0/suppressions/:address only if you are sure it is valid.

A message I expected is missing from the list. Spam, blocked, unauthenticated and trash messages are hidden unless you pass that label. Filters such as labels=received,unread need every label to match.

My reply landed in a new thread. Forwards start a new thread. For replies use the reply endpoint, which sets In-Reply-To and References.

My webhook is not called. Check enabled, the event types it subscribes to, its inbox and pod scope, and GET /v0/webhooks/:webhook_id/deliveries for the last attempts. The URL must be a public https address. Respond with a 2xx within 10 seconds; anything else is retried up to eight attempts.

My webhook signature check fails. Verify against the exact raw request body, not re-serialised JSON. Strip whsec_ and base64-decode the rest to get the key. See webhooks.

I verified my domain but mail does not flow. Expected: sending from and receiving on custom domains is not connected yet. See domains.

429 rate_limited but I am under my plan. The per-inbox cap of 100 sends in any rolling 24 hours applies on every plan, as do the per-IP and per-key request limits. Honour Retry-After.

A 5xx or a connection error. Retry with backoff and the same Idempotency-Key. The service runs on one server in early access, so short interruptions during deploys happen. See status.

The dashboard shows an error banner but the API works. Dashboard requests use a session cookie and a CSRF token; 403 csrf_failed means the page was open too long or came from another origin. Reload it.