Error Handling

HTTP Status Codes

The API uses conventional HTTP status codes to indicate success or failure.

Status	Meaning	What to do
`200 OK`	The request succeeded	Parse the response body
`400 Bad Request`	Invalid request parameters	Check your query parameters for typos
`404 Not Found`	The dataset or endpoint doesn't exist	Verify the slug and config name in the URL
`429 Too Many Requests`	Rate limit exceeded	Wait and retry with exponential backoff
`500 Internal Server Error`	Something went wrong on our end	Wait a moment and retry; report if it persists

When an error occurs, the API returns a JSON body with details:

{
  "error": {
    "code": "not_found",
    "message": "Dataset 'tea' not found for source 'unknown'"
  }
}

Field	Type	Description
`error.code`	string	Machine-readable error identifier
`error.message`	string	Human-readable description of what went wrong

Code	Meaning
`not_found`	The requested dataset or source doesn't exist
`invalid_parameter`	A query parameter has an invalid value
`rate_limited`	Too many requests in a short period
`internal_error`	An unexpected error occurred on the server