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:
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.
Rate limiting
Authenticated /v1 responses include X-RateLimit-Limit, X-RateLimit-Remaining, and
X-RateLimit-Reset on every response. When the per-minute throttle is exceeded, the response is
429 and also includes Retry-After (seconds to wait):
1{2 "error": {3 "type": "rate_limit_exceeded",4 "message": "Rate limit exceeded. Try again later.",5 "request_id": "req_8f3a..."6 }7}REST can also return 429 rate_limit_exceeded when the monthly anti-abuse request cap is hit
("Monthly API request limit reached."). See Rate limits & usage for limits,
header semantics, and how rate limiting differs from usage billing.
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
- Usage billing — which endpoints cost what
- Part matching — see batch behavior in context