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

# Errors

> How the v3 GraphQL API reports errors

The v3 API follows GraphQL error conventions. A response can contain `data`,
`errors`, or both. Always inspect the `errors` array, even when the HTTP status
is `200`.

## Error shape

```json theme={null}
{
  "errors": [
    {
      "message": "Query cost exceeds the rate limit",
      "extensions": { "code": "THROTTLED" }
    }
  ]
}
```

Machine-readable details live under `extensions`. Branch on `code`, not on
`message`.

## Common cases

| Situation | HTTP status | Code |
| - | - | - |
| Missing, malformed, or unknown token, or token for another store | `401` | none (`Unauthorized`) |
| Token lacks a scope a selected field requires | `403` | `INSUFFICIENT_SCOPE` |
| Query cost exceeds the points available | `429` | `THROTTLED` |
| Cursor is empty or invalid | `400` | `INVALID_CURSOR` |
| `first`/`after` combined with `last`/`before` | `400` | `INVALID_PAGINATION` |
| Page size outside 1–100 | `400` | none |
| Invalid mutation input | `400` | varies |

A record that does not exist is returned as `null`, not as an error.

<Note>
  Authentication failures are deliberately uniform. A bad header, an unknown
  token, a nonexistent store, and a token that belongs to another store all
  return `{ "errors": [{ "message": "Unauthorized" }] }`, so they cannot be told
  apart.
</Note>

## Handling throttling

When you receive a `THROTTLED` error, wait the number of seconds given in the
`Retry-After` header before retrying, and consider lowering query cost by
requesting smaller pages or fewer fields. See
[Rate limiting](/docs/api-reference/v3/rate-limiting).


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