Error Handling

Error Format

All errors follow a consistent JSON format with a statusCode field, an error object containing a machine-readable code and a human-readable message, and a metadata object with a correlationId for tracing:

{
  "statusCode": 404,
  "error": {
    "code": "NOT_FOUND",
    "message": "Postal code not found",
    "details": {}
  },
  "metadata": {
    "correlationId": "01a0642a-f300-765d-abd3-aac300a772e8"
  }
}

The correlationId in metadata is a UUIDv7 that uniquely identifies the request across all services. Include it when contacting support — it lets us trace the exact request path through logs.

HTTP Status Codes

Code	Description
200	Success
400	Bad Request — invalid parameters
401	Unauthorized — missing or invalid API key
404	Not Found — resource doesn't exist
429	Too Many Requests — rate limit exceeded
500	Internal Server Error

Common Errors

401 Unauthorized

Your API key is missing, invalid, or revoked. Check the Authorization header.

{
  "statusCode": 401,
  "error": {
    "code": "NO_API_KEY_PROVIDED",
    "message": "No API key provided",
    "details": {}
  },
  "metadata": {
    "correlationId": "01a0642b-17f8-788f-8536-ae8d7d32eef3"
  }
}

400 Bad Request

The request failed validation. The error.models field lists which parameter failed and why:

{
  "statusCode": 400,
  "error": {
    "message": "Validation failed",
    "code": "VALIDATION_FAILED",
    "models": {
      "_": "Invalid input: expected string, received undefined"
    }
  },
  "data": null,
  "metadata": {
    "correlationId": "01a0642a-f300-765d-abd3-aac300a772e8"
  }
}

404 Not Found

The requested resource (province, district, commune, or village) doesn't exist with the given ID or postal code.

429 Too Many Requests

You've exceeded your rate limit. See Rate Limits for details.