Errors
What each failure means and what to do about it.
Every error carries a machine-readable code, a message written for a
developer, and the request_id support will ask for.
{
"error": {
"code": "account_needs_attention",
"message": "The provider asked the end user to confirm their identity. Send them a reconnect link.",
"request_id": "req_2tKd9fQm",
"account_id": "acc_li_tom"
}
}Status codes
| Status | Meaning |
|---|---|
400 | The request is malformed. Fix it; retrying will not help. |
401 | The key is missing, wrong or revoked. |
403 | The key lacks the scope, or the account lacks the provider seat. |
404 | No such object, or it belongs to another project. |
409 | A conflict, such as connecting a provider the user already linked. |
422 | The request is valid but this provider cannot do it. |
429 | You exceeded your API rate limit, not the provider's. |
5xx | Ours. Retry with backoff; if it persists, send us the request id. |
The ones worth handling specifically
account_needs_attention
The provider wants the end user. Do not retry. Show the user the message and the reconnect link; see Account health.
capability_unavailable (422)
The provider genuinely cannot do this — server-side threading on a mailbox whose server exposes none, or a settings write on a provider without them. Check the connector page and branch at design time, not at runtime.
429 from aux0
Your own API allowance. The response carries Retry-After. If you see this
regularly it usually means a polling loop that a webhook would replace.
What is not an error
A message with status: "queued" is a success. aux0 accepted it and is
holding it inside the account's pacing window or until the account
reconnects. Retrying it is the single most common integration mistake, and
the one most likely to get an account restricted.
Getting help
Send the request_id. Every response carries one, they are retained for 30
days, and with one we can see exactly what happened instead of asking you to
reproduce it.