Errors and response envelope

Documentation index for AI agents: /llms.txt. Every page is also available as markdown: add .md to the URL.

The JSON envelope for success and error responses, status codes and retries.

Success envelope

Successful responses wrap the result in data. List endpoints add pagination details in meta:

{
  "data": [
    { "id": "32", "code": "32", "name": "JAWA BARAT", "alt_name": "Jawa Barat" }
  ],
  "meta": { "total": 38, "page": 1, "per_page": 20, "total_pages": 2 }
}

Paginated endpoints accept page and per_page query parameters. Defaults and maximums are listed per endpoint (commonly 20 per page, maximum 100).

Error envelope

Errors return an error object with a machine-readable code, a human-readable message and optional details:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "...",
    "details": {}
  }
}

Status codes

Status	Meaning	What to do
400	Invalid request	Fix the parameters or body. Not charged.
401	Missing or invalid credentials	Send a valid key in `x-api-key` (REST) or `Authorization: Bearer` (MCP).
402	Insufficient credits (error code INSUFFICIENT_CREDITS): the credit balance cannot cover this request. Add credits in the dashboard. Keys issued through RapidAPI return QUOTA_EXCEEDED when their plan's included credits run out.	No credits left for the request. Top up or change plan in the dashboard.
429	Rate limit exceeded	Wait for the number of seconds in the `Retry-After` header, then retry.
5xx	Upstream error or timeout	Retry later with backoff. Not charged.

Failed requests are not billed: only successful requests cost credits (see Pricing).