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:

json

{
  "error": "Domain not found"
}

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

typescript

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

try {
  await poststack.emails.send({ ... });
} catch (err) {
  if (err instanceof PostStackError) {
    // err.status  = 422
    // err.message = "Domain not verified"
  }
}

HTTP Status Codes

Status	Meaning	Description
`200`	OK	Request succeeded. Response body contains the result.
`201`	Created	Resource created successfully.
`400`	Bad Request	The request body is malformed or missing required fields.
`401`	Unauthorized	Missing or invalid API key.
`403`	Forbidden	API key does not have permission for this action.
`404`	Not Found	The requested resource does not exist.
`409`	Conflict	The resource already exists (e.g., duplicate domain or contact email).
`422`	Unprocessable Entity	Validation failed. The request body contains invalid data.
`429`	Too Many Requests	Rate limit exceeded. Check the Retry-After header.
`500`	Internal Server Error	Something went wrong on our end. Try again later.

Common Errors

Here are common error messages and how to resolve them:

Error	Status	Resolution
`Invalid API key`	`401`	Check that your API key is correct and starts with sk_live_ or sk_test_.
`API key does not have permission`	`403`	Use a key with full_access permission, or upgrade the key permissions.
`Domain not verified`	`422`	Verify your domain DNS records before sending. Use POST /domains/:id/verify.
`Domain not found`	`404`	Add the domain first with POST /domains.
`Contact already exists`	`409`	A contact with this email already exists. Use PATCH to update instead.
`Rate limit exceeded`	`429`	Wait and retry after the duration specified in the Retry-After header.
`Batch size exceeds limit`	`422`	Reduce batch to 100 emails or fewer per request.
`Template not published`	`422`	Publish the template with POST /templates/:id/publish before using it.
`Missing required field: to`	`400`	Include the "to" field as an array of email addresses.
`Invalid email address`	`422`	Check the email address format in the "from" or "to" fields.

Rate Limits

API rate limits depend on your plan. When you exceed the limit, the API returns a 429 status with a Retry-After header indicating how many seconds to wait:

bash

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "error": "Rate limit exceeded"
}

The SDK automatically handles rate limiting with exponential backoff and retries.