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 |
usage_limit_exceeded | 402 | A usage limit is reached — see Usage limits |
permission_error | 403 | Key lacks the required scope, or paid endpoints without an active subscription |
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, and reason when a usage limit did (see
below). Every response — success or error — includes a request_id (also in the X-Request-Id
header); quote it when contacting support.
Usage limits
When a paid request can't run because a usage limit is reached, the response is
402 usage_limit_exceeded. message says which limit, for a person — including, for an
organization, its name and when the limit resets — and reason says the same for your code:
1{2 "error": {3 "type": "usage_limit_exceeded",4 "reason": "org_spend_limit",5 "message": "Acme has reached its monthly spend limit of $5,000. Usage resumes on Nov 12, or an owner can raise the limit.",6 "request_id": "req_8f3a..."7 }8}reason | The limit that was reached |
|---|---|
out_of_credits | Your AI allowance, top-ups, and bonus credits for the period are used up |
lookups_used_up | Your part lookups for the month are used up |
org_inactive | The organization can't be used right now: its billing needs attention from an owner |
org_used_up | Your seat's included usage and the organization's shared pool are used up |
org_spend_limit | The organization's monthly spend limit is reached |
member_limit | You reached your own monthly limit in the organization, set by an owner |
org_lookups_limit | The organization's shared monthly part lookups, from its plan, are used up — for every member |
The org_* and member_limit reasons apply to requests made with an organization's API key; those
requests are billed to the organization.
- Free endpoints keep working — see Usage billing for which those are.
- Don't retry it. The request is refused without doing any work until the limit resets (the message says when), you top up, or an owner raises the limit.
- Branch on
reason, not onmessage. The message is written for people and may change. Treat areasonyou don't recognize, or a null one, as a generic usage limit: new values may be added.
What to do next: details
When your own allowance runs out (out_of_credits, lookups_used_up), the error also carries
details: what ran out, when it comes back, and only the options that would help your plan. Its
message is the same sentence as details.tell_user, written to be passed on to a person as is —
an AI agent calling the API or MCP can relay it directly.
1{2 "error": {3 "type": "usage_limit_exceeded",4 "reason": "out_of_credits",5 "message": "You've used all the AI credits on your Zenode Starter plan. They reset on Nov 25. To keep going now, add credits in any amount or upgrade to Pro ($400/mo) at https://zenode.ai/account/billing.",6 "details": {7 "exhausted": "ai_credits",8 "plan": "starter",9 "resets_at": "2026-11-25",10 "billing_url": "https://zenode.ai/account/billing",11 "options": [12 {13 "kind": "top_up",14 "description": "Add AI credits in any amount"15 },16 {17 "kind": "upgrade",18 "plan": "pro",19 "price": "$400/mo",20 "description": "Upgrade to Pro ($400/mo)"21 }22 ],23 "tell_user": "You've used all the AI credits on your Zenode Starter plan. They reset on Nov 25. To keep going now, add credits in any amount or upgrade to Pro ($400/mo) at https://zenode.ai/account/billing."24 },25 "request_id": "req_8f3a..."26 }27}| Parameter | Type | Required | Description |
|---|---|---|---|
exhausted | string | Required | ai_credits, part_lookups, or subscription (the account has no plan) |
plan | string | null | Required | Your plan: starter, pro or free |
resets_at | string | null | Required | ISO date the allowance comes back. AI credits reset on your plan's billing date, part lookups on the 1st of each month (UTC) |
billing_url | string | Required | Where to top up, change plan or subscribe |
options | object[] | Required | top_up (AI credits in any amount), upgrade (to Pro) or subscribe (plans from $40/mo). Empty when waiting for the reset is the only option |
tell_user | string | Required | One sentence to pass on to the person |
A top-up refills AI credits only, so it is never offered when part lookups run out. Requests made
with an organization's API key don't carry details: their message already names the
organization, its limit and when it resets.
Without a subscription, paid endpoints return 403 permission_error with reason
subscription_required and the same details (exhausted: "subscription", pointing to plans from
$40/mo).
Over MCP, the same refusal comes back as a tool error: the sentence for the person, then the same
details as JSON.
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