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:
{
"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 }
}
}| Field | What it is |
|---|---|
code | A stable lower-case code to branch on. It never changes for a given error. |
message | A sentence for a person, safe to show as it is. It may be reworded; do not parse it. |
details | Optional. 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:
| Status | Code |
|---|---|
| 400, 422 | invalid_request |
| 401 | unauthorized |
| 402 | payment_required |
| 403 | forbidden |
| 404 | not_found |
| 409 | conflict |
| 410 | gone |
| 413 | too_large |
| 429 | rate_limited |
| 500 and up | server_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
| Status | Code | Means |
|---|---|---|
| 401 | unauthorized | No Authorization: Bearer header, or a token of an unknown kind |
| 401 | invalid_api_key | The API key is wrong or was revoked |
| 401 | invalid_token | The OAuth access token expired, was revoked, or its connection was removed |
| 403 | plan_required | API keys need Pro or Business; connect through OAuth on Free |
| 403 | insufficient_scope | The connection lacks the scope in details.scope; WWW-Authenticate names it too |
Authentication says what to do about each.
Requests
| Status | Code | Means |
|---|---|---|
| 400 | validation_error | The body broke a rule. details.fields lists each field with its field, message and code |
| 400 | invalid_name, invalid_alias, invalid_domain, invalid_pattern | A name, alias, domain or rule pattern is not allowed; message says why |
| 400 | invalid_forward_target | Forwarding to a dissolve.email address or a known disposable service is refused |
| 400 | invalid_webhook_url | The webhook address is not public https (details.reason says why) |
| 404 | not_found | No such thing, or it is not yours. A message, inbox or label you cannot see answers the same as one that does not exist |
| 404 | not_found | No such /v1 endpoint |
| 409 | name_taken, alias_taken, conflict | The address is in use, reserved or held back, or the thing already exists |
| 410 | gone | The inbox has expired (an identity's says inbox_expired) |
Plans and ownership
| Status | Code | Means |
|---|---|---|
| 403 | upgrade_required | The feature needs a higher plan (details.requiredPlan when known): custom names, forwarding, aliases, search, webhooks, rules, labels |
| 403 | forbidden | Agent identities, personas or the vault need Pro or Business. An attachment download on Free is also forbidden, with details.code PLAN_REQUIRED |
| 403 | owner_only | You are a team member: you can read a shared inbox but only its owner can delete, extend, forward or alias it |
| 403 | plan_limit_exceeded | As many active inboxes as the plan allows |
| 403 | extension_limit_reached | Free inboxes can be extended once |
| 403 | lifetime_limit_reached | The inbox has reached the longest life the plan allows; make a new one |
| 403 | alias_limit_reached, reservation_limit | The plan's aliases per inbox or reserved names are used up |
| 400 or 429 | rule_limit, label_limit, webhook_limit, template_limit, limit_exceeded | A count limit of the plan; delete one first |
Rates and timing
| Status | Code | Means |
|---|---|---|
| 429 | rate_limited | The credential's per-minute rate is used up. Retry-After: 60 |
| 429 | too_many_waits | Five waits are already open for this credential. Retry-After: 5 |
| 429 | resource_limit_exceeded | An hourly cap, or polling the message list too often. details.resetAt says when |
| 429 | hourly_limit_exceeded | Free accounts make five inboxes an hour |
| 429 | extend_too_early | Pro 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
| Status | Code | Means |
|---|---|---|
| 500 | server_error | Something broke on our side. details.requestId matches X-Request-Id |
| 503 | MAINTENANCE | A 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:
{ "error": "invalid_grant", "error_description": "The refresh token has expired. Connect again." }error | From | Means |
|---|---|---|
invalid_request | authorize, token | A required parameter is missing, or PKCE S256 was not used |
invalid_client | authorize, token, revoke | Unknown or disabled client, or wrong client authentication |
invalid_client_metadata, invalid_redirect_uri | register | The registration was refused; the description says why |
invalid_grant | token | The code or refresh token is wrong, expired, already used or its connection removed |
invalid_scope | authorize | No requested scope is known or allowed for this client |
invalid_target | authorize | resource is not one this server serves |
unsupported_grant_type, unsupported_response_type | token, authorize | Only authorization_code, refresh_token and response_type=code exist |
access_denied | authorize redirect | The person declined |
slow_down | register, authorize, token | Too many requests from your address |
temporarily_unavailable | all | OAuth 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
429afterRetry-After,503afterRetry-After, and500,502or504on a read or a delete, with backoff. The TypeScript SDK does this for you. - Do not retry
400,401,403,404,409or410unchanged: the same request gets the same answer. Fix the request, refresh the token or change the plan first. - Be careful with creates. A
POSTthat timed out may have worked: list before you create again, or you may hold two inboxes. - A wait that answers
found: falseis 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