Errors

Error response format#

A failed request answers with a 4xx or 5xx status and a JSON body holding a readable error and a machine-readable code. Branch on code and the status: the wording of error may improve over time, the codes will not change.

HTTP/1.1 422 Unprocessable Entity
X-Request-Id: 03f82111-6c1e-4a53-9a1f-5d0c8e7b2a44

{
  "error": "Domain 'acme.com' is not verified",
  "code": "unprocessable_entity"
}

errorstring

What went wrong, in words you can show a developer. Validation errors name each failing field as path: message, joined with commas — to.0: must be a valid email address, subject: Subject is required when not using a template.

codestring

One of the codes below. Derived from the status unless the endpoint sets a more specific one.

required, missingstring[]

Only on 403 insufficient_scope: the scopes the endpoint needs and the ones your credentials lack.

missingFieldsstring[]

Only on the 400 for an empty send body: which of from, to, subject and html|text|template_id are absent.

Every response from the API — success or failure — carries an X-Request-Id header. Include it when you contact support; it finds the exact request in our logs.

Error codes#

HTTP status codes#

Each endpoint on the Emails page lists the exact statuses it returns and what triggers each one.

Common errors#

Handling errors in code#

The SDKs raise a typed error for any non-2xx response, carrying the status, the error message, the code and the request id.

import { PostStack, PostStackError } from '@poststack.dev/sdk';

try {
  await poststack.emails.send({ /* … */ });
} catch (err) {
  if (err instanceof PostStackError) {
    err.statusCode; // 422
    err.code;       // "unprocessable_entity"
    err.message;    // "Domain 'acme.com' is not verified"
    err.requestId;  // "03f82111-6c1e-…" — quote it to support
  }
  throw err;
}

from poststack import PostStack, PostStackError

try:
    ps.emails.send({...})
except PostStackError as err:
    print(err.status_code, err.code, err.error, err.request_id)
    raise

res, err := client.Emails.Send(ctx, input)
if err != nil {
    var apiErr *poststack.Error
    if errors.As(err, &apiErr) {
        log.Printf("status=%d code=%s msg=%s request_id=%s",
            apiErr.StatusCode, apiErr.Code, apiErr.Message, apiErr.RequestID)
    }
    return err
}

Retries#

Retry network errors, 408, 429 and 5xx with exponential backoff. Do not retry other 4xx responses: the same request will fail the same way until you change it.

All three SDKs do this for you — up to 3 retries by default, with full-jitter exponential backoff starting at 250 ms — and send an Idempotency-Key with every POST, so a retried email send can never deliver twice. Change the count with maxRetries (TypeScript), max_retries (Python) or WithMaxRetries (Go).

Rate limits#

This is a summary; Rate limits covers every limit and quota in detail.

Limits are counted per API key (or OAuth token, or dashboard user) and per endpoint, over fixed windows — one minute for most endpoints. Free-plan teams get half of each limit. The send endpoints allow 60 requests per minute for POST /emails and 10 for POST /emails/batch; see Rate limits → Limits by endpoint for the rest. Every rate-limited endpoint returns these headers, so you can slow down before you hit the limit:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1790686842
Retry-After: 47
Content-Type: application/json

{
  "error": "Rate limit exceeded. Please try again later.",
  "code": "rate_limit_exceeded"
}

In front of the API, the proxy also limits each source IP address to 30 requests per second (10 per second on /emails/batch), with a short burst allowance. Its 429 has no JSON body and no Retry-After; back off for a second and retry. Spreading one integration over many API keys does not raise this limit.

Troubleshooting#

Next steps