Search documentation

Search across all documentation pages

Get API Key
Concepts

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}
typeHTTPMeaning
invalid_request400Malformed body or bad parameters
authentication_error401Missing or invalid API key
usage_limit_exceeded402A usage limit is reached — see Usage limits
permission_error403Key lacks the required scope, or paid endpoints without an active subscription
not_found404The resource does not exist
rate_limit_exceeded429Too many requests — see Rate limits
server_error5xxA 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:

JSON
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}
reasonThe limit that was reached
out_of_creditsYour AI allowance, top-ups, and bonus credits for the period are used up
lookups_used_upYour part lookups for the month are used up
org_inactiveThe organization can't be used right now: its billing needs attention from an owner
org_used_upYour seat's included usage and the organization's shared pool are used up
org_spend_limitThe organization's monthly spend limit is reached
member_limitYou reached your own monthly limit in the organization, set by an owner
org_lookups_limitThe 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 on message. The message is written for people and may change. Treat a reason you 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.

JSON
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}
ParameterTypeRequiredDescription
exhausted
stringRequiredai_credits, part_lookups, or subscription (the account has no plan)
plan
string | nullRequiredYour plan: starter, pro or free
resets_at
string | nullRequiredISO 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
stringRequiredWhere to top up, change plan or subscribe
options
object[]Requiredtop_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
stringRequiredOne 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):

JSON
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