# Errors and response envelope

> Documentation index for AI agents: [/llms.txt](https://docs.apiindonesia.id/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`:

```json
{
  "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`:

```json
{
  "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](https://docs.apiindonesia.id/pricing.md)).