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

# Erros

> O formato de erro da API da CentralCart, os status usados e como tratar cada um.

Toda resposta de erro da API da CentralCart usa o mesmo envelope: um objeto com a chave
`errors`, contendo um array.

```json theme={null}
{
  "errors": [
    { "message": "Cupom de desconto não encontrado." }
  ]
}
```

## Campos

| Campo     | Tipo     | Descrição                                                                         |
| --------- | -------- | --------------------------------------------------------------------------------- |
| `message` | `string` | Mensagem legível, em português. Sempre presente.                                  |
| `code`    | `string` | Código semântico e estável do erro. Presente apenas em alguns erros. Veja abaixo. |
| `ref`     | `string` | Identificador único desta ocorrência. Presente apenas em falhas de pagamento.     |

### `code`

O `code` diz **o que** falhou, de forma estável e agrupável. Por exemplo,
`GATEWAY_CHARGE_FAILED`. Hoje ele acompanha principalmente as falhas de geração de
pagamento; a maior parte dos erros de validação vem apenas com `message`.

### `ref`

O `ref` identifica **qual ocorrência** falhou, no formato `MP-8061e7cd`. Ele aparece em
falhas de pagamento e é o valor que o comprador deve informar ao suporte. É por ele que
a equipe localiza o erro exato nos registros.

```json theme={null}
{
  "errors": [
    {
      "message": "Não foi possível gerar o pagamento. Tente outro método.",
      "code": "GATEWAY_CHARGE_FAILED",
      "ref": "MP-8061e7cd"
    }
  ]
}
```

Se você exibe erros de checkout no seu front, mostre o `ref` quando ele vier. Sem ele, o
suporte não tem como rastrear o caso.

## Status HTTP

| Status | Significado                                                                             | O que fazer                                                                               |
| ------ | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `400`  | Requisição malformada ou falha ao consultar um serviço externo.                         | Corrija a requisição. Não repita sem mudar nada.                                          |
| `401`  | Credencial ausente, inválida ou expirada.                                               | Verifique a chave de API ou o token. Não repita.                                          |
| `402`  | Loja bloqueada.                                                                         | Não repita. Fale com o suporte.                                                           |
| `403`  | O recurso não pertence a esta loja, ou falta permissão.                                 | Não repita.                                                                               |
| `404`  | Recurso não encontrado, inclusive loja não resolvida pelo `x-store-domain`.             | Confira o identificador. Não repita.                                                      |
| `422`  | Dados inválidos: campo obrigatório ausente, formato inválido, regra de negócio violada. | Corrija os dados e reenvie. A `message` diz qual campo falhou.                            |
| `429`  | Limite de requisições atingido.                                                         | Respeite o header `Retry-After`. Veja [Limites de requisição](/api-reference/rate-limit). |
| `500`  | Erro interno.                                                                           | Tente novamente com backoff exponencial. Se persistir, fale com o suporte.                |

```json theme={null}
{
  "errors": [
    {
      "message": "Resource rate limit reached.",
      "code": "RATE_LIMIT_REACHED"
    }
  ]
}
```

## Múltiplos erros

`errors` é um array porque erros de validação podem trazer mais de uma entrada, uma por
campo inválido. Trate sempre como lista.

```json theme={null}
{
  "errors": [
    { "message": "Informe um e-mail válido." },
    { "message": "Informe o seu nome completo." }
  ]
}
```

## Tratando erros no cliente

```ts theme={null}
async function request(path: string, init?: RequestInit) {
  const res = await fetch(`https://api.centralcart.io/v1${path}`, {
    ...init,
    headers: {
      'x-store-domain': 'sualoja.centralcart.ai',
      'Content-Type': 'application/json',
      ...init?.headers,
    },
  })

  if (res.ok) return res.json()

  const body = await res.json().catch(() => null)
  const first = body?.errors?.[0]

  throw Object.assign(new Error(first?.message ?? 'Erro inesperado.'), {
    status: res.status,
    code: first?.code,
    ref: first?.ref,
    retryAfter: Number(res.headers.get('Retry-After')) || undefined,
  })
}
```

<Tip>
  Só faça retry automático em `429` e `500`.
</Tip>