Skip to content

Error Handling

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 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)

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.

  1. Check the status code before parsing the response body
  2. Respect Retry-After headers on 429 and 503 responses
  3. Don’t retry 4xx errors — they indicate a client-side issue (bad key, no credits, wrong params)
  4. Retry 5xx errors with exponential backoff (the upstream source may recover)