Errors
How the Zenode API reports errors — the uniform error object, the type values, and how partial failures work in batch requests.
Errors use a uniform envelope with an appropriate HTTP status:
JSON
1{2 "error": {3 "type": "invalid_request",4 "message": "Field 'query' is required.",5 "param": "query",6 "request_id": "req_8f3a..."7 }8}type | HTTP | Meaning |
|---|---|---|
invalid_request | 400 | Malformed body or bad parameters |
authentication_error | 401 | Missing or invalid API key |
permission_error | 403 | Key lacks the required scope |
not_found | 404 | The resource does not exist |
rate_limit_exceeded | 429 | Too many requests — see Rate limits |
server_error | 5xx | A Zenode-side failure |
param is present when a specific field caused the error. Every response — success or error —
includes a request_id (also in the X-Request-Id header); quote it when contacting support.
Partial failures in batches
Batch endpoints return 200 even when individual lines fail. Inspect each line: a failed line carries
a per-line error (the same envelope, minus request_id) while its neighbors succeed. A non-2xx
status is reserved for whole-request failures — authentication, malformed JSON, exceeding the batch
cap, or rate limiting.
Next
- Rate limits & usage
- Part matching — see batch behavior in context