Errors

Every error is JSON. The shape never changes based on Accept, and never becomes an HTML error page.

{
  "success": false,
  "error": "Mailbox not found",
  "code": "mailbox_not_found"
}

Validation errors carry a per-field breakdown instead of a code:

{
  "success": false,
  "error": "Validation error",
  "issues": [
    { "path": "to.0.address", "message": "invalid email address format" },
    { "path": "subject", "message": "subject is required" }
  ]
}

path is dot-joined, so nested and array fields read as to.0.address. Map it straight onto your form fields.

Status codes

On 404 versus 403

A resource in another org returns 404, not 403. This is intentional. A 403 would confirm that the id exists, which leaks the existence of other tenants' resources to anyone willing to enumerate ids. If you get a 404 on an id you are sure about, check your X-Project-Id before assuming the resource is gone.

Send error codes

A refused send always tells you why in code, so you can branch without parsing prose. These are stable; the error message is not.

A 429 that carries Retry-After means the wait is known: honour it rather than backing off blindly. plan_limit_reached is the exception, since waiting out a monthly allowance is not a retry strategy.

What is safe to retry

Retry 5xx and network failures. Do not retry 4xx, since the same request will fail the same way.

For sends, retry only with an Idempotency-Key. Without one, a retry after a timeout can send the message twice: your connection died, but ours may have succeeded. With one, the retry returns the original result. See Sending.

Use exponential backoff with jitter. Retrying a struggling service on a fixed interval from every client at once is how a partial outage becomes a full one.

In the SDK

The client raises typed errors, so you can branch on the class instead of parsing status codes:

import {
  PostboxError,
  ValidationError,
  RateLimitError,
  AuthenticationError,
} from "@postbox/sdk";

try {
  await pb.messages.send({ from, to, subject, bodyHtml });
} catch (err) {
  if (err instanceof ValidationError) {
    for (const issue of err.issues) {
      console.error(`${issue.path}: ${issue.message}`);
    }
  } else if (err instanceof RateLimitError) {
    // back off and retry
  } else if (err instanceof AuthenticationError) {
    // the key is wrong; retrying will not help
  } else if (err instanceof PostboxError) {
    console.error(err.message, err.requestId);
  }
}

Every error carries a requestId. Include it when you contact support; it is how we find your exact request.

The client retries safe failures for you, up to maxRetries (default 2, so 3 attempts total). By the time an error reaches your catch, it has already been retried.