Responses & errors

Every endpoint returns the same JSON envelope, so integrations can handle success and failure consistently.

Success

{
  "ok": true,
  "data": { ... }
}

Failure

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "..."
  }
}

Error reference

Code	HTTP	Meaning
MISSING_KEY	401	The Authorization header is missing.
INVALID_KEY	401	The supplied key cannot be used.
RATE_LIMITED	429	The account or standalone key exceeded its per-minute request limit.
INSUFFICIENT_CREDITS	429	The account does not have enough shared credits for the request.
INVALID_INPUT	400	A required parameter is absent or a supplied value is invalid.
NOT_FOUND	404	No endpoint matches the requested versioned path.
METHOD_NOT_ALLOWED	405	The endpoint does not support that HTTP method.
PAYLOAD_TOO_LARGE	413	The JSON request body exceeds the accepted size.
UPSTREAM_UNAVAILABLE	503	API-key verification is temporarily unavailable.
INTERNAL_ERROR	500	An unexpected processing failure occurred.

Credit charging

Credits are deducted only when an endpoint completes successfully. Authentication errors, malformed JSON, oversized payloads, invalid parameters, unsupported methods, unknown paths, and internal processing failures are not charged. Two active Free keys share the same account-level monthly balance.

Credits and rate-limit headers

Authenticated responses include X-Credit-Limit, X-Credit-Remaining, X-Credit-Cost and RateLimit-Policy. A RATE_LIMITED response also includes Retry-After; it does not consume credits. Legacy X-RateLimit-Limit and X-RateLimit-Remaining headers continue to mirror the monthly credit balance for compatibility. Retry transient 5xx failures with capped exponential backoff, and retry a rate-limited request only after the indicated delay.

Browse API reference