Errors

type is a frozen set you can branch on and will never grow. code is specific and additive, so treat one you do not recognise as its type. requestId is on every response, successes included, and is what ties a report to a log line.

{  "error": {    "type": "validation_error",    "code": "invalid_email_address",    "message": "Not a valid email address: ada@",    "param": "to.0",    "docUrl": "https://nextmail.sh/docs/api/errors#invalid_email_address",    "requestId": "req_e103790543af4…"  }}

param is dotted and indexed, so it points at the exact element (to.0, attachments.2.filename) rather than at the field that contains it.

docUrl links to the row for its code in Every error code, further down this page. When this page does not list a code yet, the link opens that table instead.

Branch on type for behaviour and read code for the message you show a human. An unrecognised code is not an error in your client. It means we named a failure more precisely than we used to.

const res = await fetch(`${BASE}/emails`, { method: 'POST', headers, body }); if (!res.ok) {  const { error } = await res.json();   switch (error.type) {    case 'rate_limit_error':      throw new RateLimited(error.code);    case 'validation_error':      // error.param points at the offending field      throw new BadRequest(`${error.param}: ${error.message}`);    case 'authentication_error':      // revoked_api_key and expired_api_key are worth telling an operator apart      throw new AuthFailed(error.code);    default:      // quote requestId when you report it      throw new Unexpected(error.message, error.requestId);  }}

No plan caps how many webhooks, keys, addresses, templates, rules, roles or audiences a workspace has. Each one does carry a soft limit, a guard against a runaway script or a leaked key filling a workspace, and reaching it is a 422 workspace_limit_reached whose message names the limit. Nothing was created, so retrying the same call fails the same way until the workspace is below the limit again. Members are not limited at all.

Only an OAuth access token meets these. Before a sensitive change, such as deleting a domain or changing a webhook, the API asks the app for a verification code from the person it acts for, the same code the web app would ask them for. Authentication lists the operations and the two calls that verify a code.

Every code the API sends, in alphabetical order, with the statuses and types it comes with. The docUrl of an error links to the row for its code.

Each API key, and each access token an app holds, may make 600 requests a minute, counted across every endpoint. The minute is a fixed window that starts on the minute of the clock, and every answer to a key or an app carries the count, so a client can slow down before it is refused.

The request after the last one a window allows is a 429 rate_limited, and its Retry-After is the rest of the window. Nothing it asked for was done, so send it again once the wait is over. Every other 429 carries Retry-After as well: the length of its own window for a throttle such as upload_rate_limited, the seconds to midnight UTC for a daily allowance such as ai_quota_exceeded, and the seconds to the first of the month for send_quota_exceeded.