Error Handling
What it does
Structured error responses with consistent HTTP status codes, error codes, and human-readable messages across all API endpoints. Every error includes a machine-readable code for programmatic handling and a message for debugging.
How to use it
Check HTTP status
POTAL uses standard codes: 400 (bad request), 401 (unauthorized), 404 (not found), 429 (rate limited), 500 (server error).
Parse error body
Error responses include success: false, error.code (e.g., "INVALID_COUNTRY"), and error.message.
Handle by code
Use the error code in your application logic — codes are stable across API versions.
Retry on 5xx
Server errors are transient — retry with exponential backoff. 4xx errors require fixing the request.
Related Features
155+ API endpoints with consistent JSON responses
Stable v1 API with backward-compatible versioning strategy
Interactive API docs with code examples in 5 languages
Intelligent rate limiting with per-plan quotas and burst support
Automatic webhook retry with exponential backoff on failure