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

# Errors & Rate Limits

> Error response shape, status codes, and the rate limit

## Error shape

Every error response is JSON with at least:

```json theme={null}
{
  "error": "insufficient_credits",
  "message": "Not enough credits for this request",
  "request_id": "b3f1c2...",
  "credits_remaining": 0
}
```

* **`error`** — a short machine-readable code (see table below).
* **`message`** — a human-readable description.
* **`request_id`** — unique per call; include this if you contact support
  about a specific request.
* **`credits_remaining`** — present on most errors that occur after
  authentication, so you can tell your balance without a separate
  `/v1/usage` call. Absent on errors that happen before your key is even
  charged (e.g. bad auth, bad request body).

A `422` ("no result found") response additionally includes
`credits_charged`, since some endpoints still charge on a clean miss — see
[Credits & Pricing](/horizon/credits-and-pricing#charging-on-misses). In the rare
case a compensating refund itself fails, you may also see
`"refund_issue": true` — this means the charge may not have been refunded
yet; contact support with the `request_id` and it'll be reconciled.

## Status codes

| Status | `error`                | Meaning                                                                                                    |
| ------ | ---------------------- | ---------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_request`      | Request body failed validation (missing/malformed fields). Nothing was charged.                            |
| `401`  | `unauthorized`         | Missing `Authorization` header, or the key is invalid/revoked.                                             |
| `402`  | `insufficient_credits` | Your balance is too low for this call's price. The vendor is never called.                                 |
| `422`  | `not_found`            | The vendor was called successfully but found no result. May still be charged — see above.                  |
| `429`  | `rate_limited`         | You've exceeded the rate limit (below). Nothing was charged.                                               |
| `502`  | `vendor_error`         | The upstream data vendor errored or timed out. Any reserved credits are refunded in full.                  |
| `503`  | `vendor_capacity`      | This endpoint is temporarily unavailable due to a vendor capacity limit. Nothing was charged; retry later. |

A `200` response is always success — a real payload with a normal charge, or
in a couple of specific cases (see the "charged on success only" endpoint in
[Credits & Pricing](/horizon/credits-and-pricing)) a payload with `credits_charged: 0`.

## Rate limit

**60 requests per minute per API key**, enforced with a fixed one-minute
window. Going over returns `429` before any credits are touched or any
vendor is called. There's no separate burst allowance today — spread out
high-volume workloads across the minute rather than bursting.