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

# Errors

> Rangler returns errors in one consistent format so integrations can handle failures reliably.

Rangler does not add generic `status/message/data` fields around successful responses.

* successful reads return resource-shaped JSON
* list endpoints return list-shaped JSON
* errors always use the format below

## Error format

```json theme={null}
{
  "error": {
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "28fa6152-7081-492e-8a7e-00beb237b689"
  }
}
```

## Fields

| Field | Type | Meaning |
| - | - | - |
| `error.type` | string | Broad error class |
| `error.code` | string | Stable application code for programmatic handling |
| `error.message` | string | Message describing the error |
| `error.request_id` | string | Request correlation ID for support and debugging |
| `error.details` | object or array or `null` | Optional structured context |

## Common status codes

| Status | Meaning | Typical cause |
| - | - | - |
| `400` | Bad Request | malformed request shape or unsupported parameters |
| `401` | Unauthorized | missing, invalid, expired, revoked, or wrong-environment key |
| `403` | Forbidden | organization inactive or action not allowed |
| `404` | Not Found | company, filing, or other resource does not exist |
| `409` | Conflict | resource-state conflict, or an idempotency-key conflict on an endpoint that documents idempotent writes |
| `422` | Unprocessable Entity | validation failure |
| `429` | Too Many Requests | rate limit exceeded |
| `500` | Internal Server Error | unexpected Rangler error |

## Example: missing authentication

The financial endpoint returned this response when called without an API key:

```json theme={null}
{
  "error": {
    "type": "unauthorized",
    "code": "unauthorized",
    "message": "Authentication required.",
    "request_id": "28fa6152-7081-492e-8a7e-00beb237b689"
  }
}
```

## Example: unknown financial selector

Rangler rejects unknown selector keys instead of silently returning a different dataset:

```json theme={null}
{
  "error": {
    "type": "unknown_ratio",
    "code": "unknown_ratio",
    "message": "Unknown ratio value(s): net_margin",
    "request_id": "7e4f2525-ca82-4f1a-a261-005c757c92cf",
    "details": {
      "allowed": [
        "gross_margin",
        "net_interest_margin",
        "pat_margin",
        "return_on_equity"
      ]
    }
  }
}
```

## Example: rate limited

```json theme={null}
{
  "error": {
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "28fa6152-7081-492e-8a7e-00beb237b689"
  }
}
```

## Headers worth handling

When Rangler rate limits a request, integrations should check:

* `Retry-After`
* `X-RateLimit-Limit`
* `X-RateLimit-Remaining`
* `X-RateLimit-Reset`


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