Skip to content
docs
Browse the docsErrors

Reference

Errors

The one error shape every /v1 endpoint answers with, how its codes are formed, the codes you will meet with what to do about each, OAuth errors and when to retry.

Every /v1 error has the same shape, whatever went wrong:

JSON
{
  "error": {
    "code": "plan_limit_exceeded",
    "message": "You've reached your limit of 10 active inboxes on the pro plan. Upgrade to Business for more.",
    "details": { "limit": 10, "current": 10, "tier": "pro", "upgradeTier": "business", "upgradeCta": true }
  }
}
FieldWhat it is
codeA stable lower-case code to branch on. It never changes for a given error.
messageA sentence for a person, safe to show as it is. It may be reworded; do not parse it.
detailsOptional. Whatever else the error knows: the limit and usage, the invalid fields, the scope that was missing, when to try again.

Every answer, error or not, carries an X-Request-Id header. Quote it when you write to support.

How codes are formed

/v1 runs the same handlers as the app, then puts their errors in this envelope. When a handler names its error (PLAN_LIMIT_EXCEEDED), the code is that name in lower case (plan_limit_exceeded). When it does not, the code comes from the HTTP status:

StatusCode
400, 422invalid_request
401unauthorized
402payment_required
403forbidden
404not_found
409conflict
410gone
413too_large
429rate_limited
500 and upserver_error

Any other fields the handler sent move into details. Branch on the status first and the code second.

Codes you will meet

Credentials and scopes

StatusCodeMeans
401unauthorizedNo Authorization: Bearer header, or a token of an unknown kind
401invalid_api_keyThe API key is wrong or was revoked
401invalid_tokenThe OAuth access token expired, was revoked, or its connection was removed
403plan_requiredAPI keys need Pro or Business; connect through OAuth on Free
403insufficient_scopeThe connection lacks the scope in details.scope; WWW-Authenticate names it too

Authentication says what to do about each.

Requests

StatusCodeMeans
400validation_errorThe body broke a rule. details.fields lists each field with its field, message and code
400invalid_name, invalid_alias, invalid_domain, invalid_patternA name, alias, domain or rule pattern is not allowed; message says why
400invalid_forward_targetForwarding to a dissolve.email address or a known disposable service is refused
400invalid_webhook_urlThe webhook address is not public https (details.reason says why)
404not_foundNo such thing, or it is not yours. A message, inbox or label you cannot see answers the same as one that does not exist
404not_foundNo such /v1 endpoint
409name_taken, alias_taken, conflictThe address is in use, reserved or held back, or the thing already exists
410goneThe inbox has expired (an identity's says inbox_expired)

Plans and ownership

StatusCodeMeans
403upgrade_requiredThe feature needs a higher plan (details.requiredPlan when known): custom names, forwarding, aliases, search, webhooks, rules, labels
403forbiddenAgent identities, personas or the vault need Pro or Business. An attachment download on Free is also forbidden, with details.code PLAN_REQUIRED
403owner_onlyYou are a team member: you can read a shared inbox but only its owner can delete, extend, forward or alias it
403plan_limit_exceededAs many active inboxes as the plan allows
403extension_limit_reachedFree inboxes can be extended once
403lifetime_limit_reachedThe inbox has reached the longest life the plan allows; make a new one
403alias_limit_reached, reservation_limitThe plan's aliases per inbox or reserved names are used up
400 or 429rule_limit, label_limit, webhook_limit, template_limit, limit_exceededA count limit of the plan; delete one first

Rates and timing

StatusCodeMeans
429rate_limitedThe credential's per-minute rate is used up. Retry-After: 60
429too_many_waitsFive waits are already open for this credential. Retry-After: 5
429resource_limit_exceededAn hourly cap, or polling the message list too often. details.resetAt says when
429hourly_limit_exceededFree accounts make five inboxes an hour
429extend_too_earlyPro and Business inboxes can be extended only near the end. details.availableAt says when

Rate limits and plans has the figures behind each.

Our side

StatusCodeMeans
500server_errorSomething broke on our side. details.requestId matches X-Request-Id
503MAINTENANCEA short maintenance window. This one answer is not in the envelope: it is { "error": "MAINTENANCE", "message", "until" } with Retry-After: 60

OAuth endpoints

/oauth/register, /oauth/authorize and /oauth/token answer the way OAuth 2.1 specifies, not with the envelope above:

JSON
{ "error": "invalid_grant", "error_description": "The refresh token has expired. Connect again." }
errorFromMeans
invalid_requestauthorize, tokenA required parameter is missing, or PKCE S256 was not used
invalid_clientauthorize, token, revokeUnknown or disabled client, or wrong client authentication
invalid_client_metadata, invalid_redirect_uriregisterThe registration was refused; the description says why
invalid_granttokenThe code or refresh token is wrong, expired, already used or its connection removed
invalid_scopeauthorizeNo requested scope is known or allowed for this client
invalid_targetauthorizeresource is not one this server serves
unsupported_grant_type, unsupported_response_typetoken, authorizeOnly authorization_code, refresh_token and response_type=code exist
access_deniedauthorize redirectThe person declined
slow_downregister, authorize, tokenToo many requests from your address
temporarily_unavailableallOAuth is switched off on this server

Once the client and redirect address are known good, authorize errors come back to your redirect address as error, error_description, state and iss; before that they are shown as JSON.

When to retry

  • Retry 429 after Retry-After, 503 after Retry-After, and 500, 502 or 504 on a read or a delete, with backoff. The TypeScript SDK does this for you.
  • Do not retry 400, 401, 403, 404, 409 or 410 unchanged: the same request gets the same answer. Fix the request, refresh the token or change the plan first.
  • Be careful with creates. A POST that timed out may have worked: list before you create again, or you may hold two inboxes.
  • A wait that answers found: false is not an error: nothing arrived in time. Call it again.

Something wrong or missing on this page? Tell us at support@dissolve.email.View as Markdown