Errors

PostStack uses standard HTTP status codes and returns JSON error responses. All error responses follow the same format.

Error Response Format

All error responses include an error field with a human-readable message and a stable, machine-readable code you can branch on (the wording may change; the code will not):

{
  "error": "Domain not found",
  "code": "not_found"
}

The SDK throws typed errors that you can catch and inspect:

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

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

HTTP Status Codes

Common Errors

Here are common error messages and how to resolve them:

Rate Limits

Rate-limited endpoints (sending, and most create/update routes) carry three headers describing your current bucket so you can back off proactively instead of waiting for a 429. Limits are counted per API key and per endpoint:

When you exceed the limit the API returns a 429 with the same X-RateLimit-* headers plus Retry-After:

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

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

The SDK automatically retries 408, 429 and 5xx responses (and network errors) with exponential backoff — up to 3 retries by default, configurable with the maxRetries option.