Errors

Every response uses the same envelope, so success and failure are easy to branch on.

Response envelope

A success wraps its payload; a failure carries a human-readable message and, for validation errors, a list of field issues.

// success
{ "ok": true, "data": { /* ... */ } }

// failure
{
  "ok": false,
  "message": "Validation failed",
  "issues": [{ "path": "url", "message": "Required" }]
}

Validation

Request bodies are validated at the boundary. When a field is wrong, the response lists each problem with a stable path and a message, so you can map errors back to your inputs.

HTTP status codes

400 — invalid body or parameters
401 — missing or invalid API key
402 — insufficient credit balance for a paid action
403 — your plan doesn't include API access
404 — unknown capability or resource
502 — an upstream provider failed