Error Handling
Error Response Format
Section titled “Error Response Format”Errors come in two shapes, depending on where they were raised.
Gateway errors (authentication, credits, rate limits, routing, timeouts)
have error and code fields:
{ "error": "Human-readable message", "code": "MACHINE_READABLE_CODE"}Endpoint errors (bad parameters, no data for a location, a data source
being unavailable) are returned by the endpoint itself and have a detail
field instead:
{ "detail": "Human-readable message"}For parameter validation errors (422), detail is a list describing each
invalid field.
Status Codes
Section titled “Status Codes”| Status | Code | Meaning |
|---|---|---|
| 200 | — | Success |
| 400 | — (detail) |
Invalid request, e.g. coordinates out of range |
| 401 | UNAUTHORIZED |
Missing or invalid API key |
| 402 | CREDITS_EXHAUSTED |
Insufficient credits |
| 403 | FORBIDDEN / IP_BLOCKED |
Endpoint not on your tier, or IP not in allowlist |
| 404 | NOT_FOUND or detail |
Endpoint does not exist, or no data for that request |
| 405 | METHOD_NOT_ALLOWED |
Data endpoints accept GET, POST and DELETE |
| 413 | — | Request body too large |
| 422 | — (detail) |
A parameter is missing or has the wrong type or range |
| 429 | RATE_LIMITED |
Too many requests per minute (see Rate Limits) |
| 502 | UPSTREAM_ERROR |
Pxie’s data backend could not be reached |
| 503 | SERVICE_UNAVAILABLE or detail |
Pxie or an external data source is temporarily down |
| 504 | UPSTREAM_TIMEOUT |
No response within 15 seconds (120 seconds for agriculture endpoints other than /soil and /moisture) |
Upstream Errors
Section titled “Upstream Errors”Pxie’s endpoints read from external data sources (NOAA, GFZ, etc.). If a source
fails, the endpoint’s own status code is passed through to you — usually 503,
often with a Retry-After header. If Pxie’s backend can’t be reached you get
502; if it doesn’t answer in time, 504.
Credits are only deducted on successful responses (status below 400). No error — 4xx or 5xx — is ever charged.
Best Practices
Section titled “Best Practices”- Check the status code before parsing the response body
- Respect
Retry-Afterheaders on 429 and 503 responses - Don’t retry 4xx errors — they indicate a client-side issue (bad key, no credits, wrong params)
- Retry 5xx errors with exponential backoff (the upstream source may recover)
