API: Errors

Postbox uses different error formats depending on the endpoint type.

Form management API errors

Endpoints under /api/forms/*:

Status	Scenario	Body
401	Invalid or missing API key	Unauthorized (plain text)
404	Form not found	{ "errors": "Form not found" }
422	Validation errors	{ "errors": { "field": ["message"] } }

Submission management API errors

Endpoints under /api/forms/{id}/submissions/*:

Status	Scenario	Body
400	Invalid pagination parameters	{ "error": { "code": 400, "message": "Invalid pagination parameters" } }
404	Form or submission not found	{ "error": { "code": 404, "message": "Form not found" } }
422	Could not delete submission	{ "error": { "code": 422, "message": "Could not delete submission" } }

Public submission endpoint errors

The submission endpoint (POST /api/.../f/{slug}):

Status	Scenario	Body
400	Validation error	{ "error": { "code": "validation_error", "message": "Validation failed", "details": { "field": ["message"] } } }
401	Missing auth for private form	{ "error": { "code": "unauthorized", "message": "..." } }
404	Form not found	{ "error": { "code": "form_not_found", "message": "Not found" } }
429	Submission limit reached (free)	{ "error": { "code": "plan_limit_exhausted", "message": "...", "upgrade_url": "https://usepostbox.com/settings/billing" } }

Rate limit errors

When rate limited, the response returns 429 Too Many Requests with retry_after in seconds:

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Try again in 45 seconds."
  }
}

Note

Proactive rate limit headers (e.g., X-RateLimit-Remaining) are not included on successful responses. Implement backoff based on 429 responses and the retry_after value.

Handling errors

Best practices:

• Always check the HTTP status code first
• Parse the code field for programmatic handling
• Display the message field to users
• On 429, respect the retry_after value
• On 5xx, retry with exponential backoff
• Check for upgrade_url in the error body to surface upgrade prompts to users