Error Handling
Understand API error responses and status codes
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, revoked, or expired. Send the key in the
x-api-key header.
{
"statusCode": 401,
"error": {
"code": "TOSKEY_API_KEY_MISSING",
"message": "API key is required. Provide it via the x-api-key or Authorization header."
},
"metadata": {
"correlationId": "01a0642b-17f8-788f-8536-ae8d7d32eef3"
}
}The API is fronted by the TosKey gateway. Depending on the project's error-code
namespace, auth failures appear either with a TOSKEY_ prefix
(TOSKEY_API_KEY_MISSING, TOSKEY_API_KEY_INVALID) or unprefixed
(API_KEY_MISSING, API_KEY_INVALID) — the two spellings are equivalent. A
missing key produces *_API_KEY_MISSING; a supplied key that cannot be
authenticated produces *_API_KEY_INVALID.
A supplied key that is invalid, revoked, expired, or unknown is intentionally
indistinguishable — all of them produce the same *_API_KEY_INVALID response.
Check that the key is correct and active on your dashboard rather than probing
for a more specific reason.
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"
}
},
"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.