All errors return a consistent JSON envelope with a machine-readable code, human message, and request ID for support.
{
"success": false,
"error": {
"code": "LOCATION_NOT_RESOLVED",
"message": "The supplied location could not be resolved.",
"request_id": "req_abc123"
}
}| Code | HTTP | Description |
|---|---|---|
| INVALID_INPUT | 400 | Request body or query failed validation. |
| UNAUTHORIZED | 401 | Missing or invalid credential. |
| FORBIDDEN | 403 | Credential valid but action not permitted. |
| NOT_FOUND | 404 | Resource does not exist. |
| CONFLICT | 409 | Duplicate or conflicting state. |
| QUOTA_EXCEEDED | 402 | Plan quota exceeded. |
| UNSUPPORTED_INPUT | 422 | Input format not recognized. |
| LOCATION_NOT_RESOLVED | 422 | Could not resolve a location. |
| LOCATION_AMBIGUOUS | 422 | Multiple candidates; refine input. |
| INVALID_COORDINATES | 400 | Coordinates out of valid range. |
| COUNTRY_NOT_SUPPORTED | 422 | Country not yet supported. |
| PROVIDER_UNAVAILABLE | 503 | Upstream provider unavailable. |
| PROVIDER_RATE_LIMITED | 503 | Upstream provider rate limited. |
| RATE_LIMITED | 429 | Too many requests. |
| INTERNAL | 500 | Unexpected server error. |