Errors

Errors use one JSON shape:

{
  "status": 400,
  "type": "errors/invalid_parameters",
  "title": "Invalid parameters",
  "detail": "limit must be between 1 and 250"
}

type stays the same, so check it in your code. detail explains this case and is meant for logs, not for your users.

Status	`type`	When	What to do
400	`errors/invalid_parameters`	A field is missing or wrong, for example an `account_id` in a query or body that isn’t an `acc_…` id	Fix the request. `detail` names the field
401	`errors/unauthorized`	Missing, wrong or revoked API key	Check the `X-API-KEY` header
401	`errors/invalid_credentials`	The provider rejected the mailbox’s password or token	Ask the user for the new password and reconnect the account
404	`errors/not_found`	No such account, email, attachment, draft, folder, webhook endpoint or API key, or the email no longer exists at the provider. An id in the URL path with the wrong prefix, or a plain UUID, is also not found	Check the id. Don’t retry
409	`errors/already_exists`	The mailbox is already connected	Use the existing account, or reconnect it
422	`errors/provider_rejected`	The provider refused the action, for example a recipient it won’t send to or an attachment that’s too large	Read `detail`. Retrying the same request won’t help
502	`errors/provider_error`	The provider failed or timed out	Retry later, with a backoff
500	`errors/unexpected_error`	A problem in the engine	Retry later. If it keeps happening, check the engine’s logs

For 500 errors, detail is always Something went wrong on our side., so internal details never leak. The full error is in the engine’s logs.