> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perceptlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Perceptlayer is a web data API: one key for structured JSON from about 250 websites. Base URL https://api.perceptlayer.com.
> Send the key in the X-API-Key header. GET parameters go in the query string; POST parameters in a JSON body.
> A successful call costs the credits on its endpoint (X-Credits-Used); failed calls cost nothing. Errors are {"error": {"code", "message", "request_id"}}.
> AI agents can use every endpoint through the MCP server at https://api.perceptlayer.com/mcp (tools search_endpoints, get_endpoint, call_endpoint), with Authorization: Bearer <key>.
> Get a free key at https://perceptlayer.com/signup.

# Errors

> Error codes, what they mean and what to do about them.

Errors use HTTP status codes and one JSON shape:

```json theme={"dark"}
{
  "error": {
    "code": "invalid_parameters",
    "message": "The request parameters are invalid.",
    "request_id": "..."
  }
}
```

`message` is written for people and safe to show to your users. Branch on `code`, not on `message`. No error is ever billed: `X-Credits-Used` is 0.

| Status | Code | Meaning |
| - | - | - |
| 401 | `invalid_api_key` | Missing, unknown or revoked API key. |
| 402 | `insufficient_credits` | Your credit balance is used up. Buy more credits to continue. |
| 403 | `restricted_endpoint` | This endpoint requires accepting the restricted-endpoint terms in your dashboard. |
| 404 | `unknown_endpoint` | No such endpoint. See the API reference for available endpoints. |
| 404 | `not_found` | No data was found for these parameters. You were not charged. |
| 410 | `endpoint_retired` | This endpoint has been retired. |
| 422 | `invalid_parameters` | The request parameters are invalid. |
| 429 | `rate_limited` | Too many requests. Retry after the number of seconds in the Retry-After header. |
| 502 | `source_error` | The data source returned an error. You were not charged. |
| 503 | `temporarily_unavailable` | The data source is busy. Retry after the number of seconds in the Retry-After header. You were not charged. |
| 504 | `timeout` | The data source did not answer within 60 seconds. You were not charged. |

## Retrying

* **Retry after a wait:** `429 rate_limited` and `503 temporarily_unavailable` carry a `Retry-After` header in seconds.
* **Retry later, perhaps with other parameters:** `502 source_error` and `504 timeout`.
* **Don't retry unchanged:** `401`, `402`, `403`, `404`, `410` and `422` will fail the same way until you change the key, the balance, the terms or the request.

Quote the `request_id` when you contact support.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.