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

# Erros e paginação

> RFC 7807, por que 404 no lugar de 403, e cursor no lugar de offset.

## Erros seguem RFC 7807

Content-type `application/problem+json`:

```json theme={null}
{
  "type": "about:blank",
  "title": "Requisição inválida",
  "status": 422,
  "errors": [
    { "field": "sold_at", "message": "ISO 8601 COM offset, ex.: 2026-08-07T11:49:12-03:00." }
  ]
}
```

| Status | Quando                                                                          |
| ------ | ------------------------------------------------------------------------------- |
| `401`  | Token ausente, inválido, expirado ou revogado. O motivo vem em `detail`.        |
| `403`  | O token não tem a capacidade exigida — ou é `read` e você usou `POST`/`DELETE`. |
| `404`  | Não existe **ou** é de outra empresa.                                           |
| `422`  | Validação. Veja `errors[]`.                                                     |

### Por que `404` e não `403` para recurso de outra empresa

Um `403` confirmaria que aquele id existe em algum lugar. Repetido em sequência,
isso transforma a API num oráculo: dá para descobrir quais ids são reais sem ter
acesso a nenhum deles. Então recurso de outro tenant e recurso inexistente
respondem a mesma coisa — de propósito.

## Paginação é por cursor

```bash theme={null}
curl "https://app.metricaas.com.br/v1/leads?limit=100" -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{ "data": [ … ], "next_cursor": "1786112507619_3df0cc9b-7627-4450-bb54-8a2cd9303fa2" }
```

Passe o valor em `?cursor=` para a próxima página. Quando `next_cursor` vier `null`,
acabou.

<Note>
  Não existe `offset` de propósito. O worker cria lead continuamente: entre a página
  1 e a página 2, leads novos entram no topo da ordenação e empurram o resto. Com
  `offset` você reveria linhas já lidas e pularia outras — numa varredura de base
  inteira, silenciosamente. O cursor é ancorado em `(created_at, id)` e não sofre
  disso.
</Note>

Teto de `limit`: **200**.

## Idempotência

Em `POST /v1/sales`, use `external_source` + `external_id`. Ver
[Vendas](/conceitos/vendas).