Guide

Error codes

Every error the API returns, what it means, and how to recover.

Errors return a non-2xx status and a JSON body with a stable machine-readable code. Branch on the code, never on the message - messages are written for humans and may be reworded.

json

{
  "success": false,
  "error": {
    "code": "insufficient_credits",
    "message": "This call costs 10 credits and your balance is 3. Top up to continue.",
    "details": null
  },
  "creditsCharged": 0,
  "creditsRemaining": 3
}

Reference

Status	Code	Meaning and fix
400	`invalid_arguments`	An argument is missing or the wrong type. `details` lists each problem by field. Not charged.
400	`invalid_url`	A URL argument is not an absolute http/https URL.
400	`invalid_hash`	The supplied hash is not in the expected format for that algorithm.
401	`unauthorized`	The key is missing, malformed or revoked. Check the `Authorization` header.
402	`insufficient_credits`	Balance is below the call price. Top up. Nothing was charged.
403	`account_suspended`	The account is blocked. Contact support.
404	`unknown_tool`	No endpoint with that key. Check the reference for the exact spelling.
502	`upstream_unreachable`	The host you targeted did not respond. Charged - the attempt was made on your behalf.
502	`upstream_timeout`	The target took too long. Refunded.
502	`internal_error`	A fault on our side. Refunded. Retry; if it persists, contact support.
503	`tool_disabled`	That endpoint is temporarily switched off. Not charged.

Retrying safely

Retry 502 and 503 with exponential backoff - these are transient and the refunded ones cost nothing.
Never retry 400, 401 or 403 without changing the request; the outcome will be identical.
Treat 402 as a stop condition, not a retry. Looping on it will not succeed until the balance changes.
Every endpoint is read-only or side-effect free, so a retry can never duplicate work you have already paid for.