Every response has a success boolean. On failure the HTTP status is 4xx/5xx and the body also carries a short machine code and a human message.
Error shape
{
"success": false,
"error": "NoInput",
"message": "Provide at least one token in \"tokens\"."
}Common codes
| HTTP | error | When |
|---|---|---|
| 400 | UnknownTool | The tool isn't recognised. See GET /api/v1/tools. |
| 400 | NoInput | No tokens / input were provided. |
| 400 | BadPaymentMethod | payment_method isn't one of auto/wallet/license/request. |
| 400 | BadAmount / BadMethod | Payment amount out of range, or unknown rail. |
| 401 | Unauthorized | Missing or invalid API key. |
| 402 | NotFree | payment_method: "request" but the tool isn't free right now. |
| 402 | InsufficientFunds | Wallet balance too low for the run. |
| 403 | LicenseRequired | payment_method: "license" without an active license. |
| 403 | AccountSuspended / AccountLimited | Your account can't run tasks. |
| 404 | NotFound | Unknown job / payment id. |
| 429 | RateLimited | Too many requests - slow down. |
| 503 | Maintenance | That tool is temporarily under maintenance. |
Always check
successDon't rely on the HTTP status alone - branch on success, and surface message to users and error to your logs.