Errors

The API uses standard HTTP status codes. Successful requests return 200. Errors return a JSON body with a short message, in one of these shapes:

{ "error": "..." }

{ "message": "..." }

(Validation errors use message; most other errors use error. In development builds a traceback field may also be present.)

Status codes

Code Meaning Typical cause
200 OK Request succeeded
400 Bad Request Invalid or malformed parameters — unknown model, bad date format, out-of-range coordinates, an unsupported variable for the model, or an invalid combination (e.g. a non-harmonized variable in a multi-model query)
401 Unauthorized Missing or invalid API key
403 Forbidden The key is valid but lacks access to the requested model/resource
404 Not Found No data for the query, or a NetCDF file that has not finished generating yet
405 Method Not Allowed Wrong HTTP method for the endpoint
406 Not Acceptable A response format that cannot be served was requested
410 Gone The requested dataset has been removed
429 Too Many Requests A rate limit or concurrency/credit quota was exceeded
500 Internal Server Error Unexpected server-side error
503 Service Unavailable Temporarily unavailable, e.g. a requested NetCDF file failed to compute

Notes

  • Validation (400) errors describe the offending parameter and the allowed values, so read the message — e.g. an out-of-range latitude reports the model's valid bounds, and an unsupported variable lists the model's available variables.
  • NetCDF downloads: while a file is still being generated the download endpoint returns 404 ("not completed yet"); a 503 means the file failed to compute. Retry the 404 case or use wait=true on the request — see Output formats.
  • Retries: 429, 500, and 503 are generally safe to retry with backoff; 400/401/ 403 indicate a request that must be changed before retrying.