Skip to main content

​
Error shape

Failed requests return a structured body with a human-readable error, a machine-readable code, optional details, and the standard meta object: 
{
  "error": "Valid API key required",
  "code": "INVALID_API_KEY",
  "details": null,
  "meta": {
    "requestId": "req_...",
    "timestamp": "2026-01-01T00:00:00.000Z"
  }
}
Quote meta.requestId when contacting support — it correlates with the server log line for your request.

​
HTTP status codes

StatusMeaning
400Request validation failed (VALIDATION_ERROR)
401API key missing, invalid, revoked, or expired
403Insufficient scope, IP not allowed, or not the resource owner
404Resource not found
409Conflict — e.g. a paywall slug already exists within the service
429Rate limit exceeded
503A dependency check failed (health endpoint only)

​
Error codes

The code field is stable and safe to branch on:
CodeTypical status
INVALID_API_KEY401
KEY_REVOKED401
KEY_EXPIRED401
KEY_INACTIVE401
INSUFFICIENT_SCOPE403
IP_NOT_ALLOWED403
FORBIDDEN403
NOT_FOUND404
VALIDATION_ERROR400
CONFLICT409
RATE_LIMITED429
KEY_LIMIT_REACHED403
SSRF_BLOCKED400
ALREADY_REVOKED409
INVALID_WALLET400
INVALID_SERVICE400
BETA_LIMIT_PAYWALLS403
BETA_LIMIT_SERVICES403
INTERNAL_ERROR500
DATABASE_ERROR500

​
Rate limits

Each API key may make up to 1000 requests per 60-second window. When you exceed it, the API responds with 429 Too Many Requests and a Retry-After header indicating how many seconds to wait: 
HTTP/1.1 429 Too Many Requests
Retry-After: 23

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED",
  "meta": { "requestId": "req_...", "timestamp": "2026-01-01T00:00:00.000Z" }
}
Back off for the number of seconds in Retry-After before retrying. Spread bursty workloads across the window to stay under the limit.

Authentication

Key format, header options, and scopes that drive 401 and 403 responses.