Erros e Limites

Formato de erro, códigos e limites de requisição da API Aprovei (https://api.aproveicheckout.com.br/v1). Os erros de PIX estão documentados na página de PIX.

Formato de Erro

Respostas de erro seguem o formato abaixo, sempre em JSON:

JSON

{
  "status": "error",
  "code": "VALIDATION_ERROR",
  "message": "Dados inválidos.",
  "errors": {}
}

Códigos de Erro

Código	Quando ocorre
`AUTH_MISSING_BEARER_TOKEN`	Token Bearer ausente
`AUTH_INVALID_BEARER_TOKEN`	Token Bearer inválido
`AUTH_STORE_HEADER_MISSING`	Header `X-Store-Slug` ausente
`AUTH_STORE_FORBIDDEN`	Token sem acesso à loja informada
`AUTH_IP_NOT_ALLOWED`	IP fora da allowlist do token
`UNSUPPORTED_MEDIA_TYPE`	POST sem `Content-Type: application/json` (HTTP 415)
`VALIDATION_ERROR`	Payload inválido
`IDEMPOTENCY_KEY_MISSING`	`Idempotency-Key` ausente no checkout
`IDEMPOTENCY_KEY_CONFLICT`	Mesma chave com payload diferente
`CHECKOUT_DOMAIN_NOT_CONFIGURED`	Loja sem domínio ativo para vendas
`PRODUCT_NOT_FOUND`	Produto ou variante inexistente/inativo (HTTP 404)
`STOCK_UNAVAILABLE`	Estoque insuficiente para um ou mais itens
`WEBHOOK_LIMIT_EXCEEDED`	Limite de 10 webhooks por loja atingido
`RATE_LIMIT_EXCEEDED`	Limite de requisições atingido (HTTP 429, com header `Retry-After`)
`NOT_FOUND`	Rota ou recurso inexistente (HTTP 404)
`INTERNAL_ERROR`	Erro inesperado no servidor (HTTP 5xx)

Rate Limits

Grupo	Limite (por token + loja)
Storefront (loja, produtos, busca)	`300/min`
Listagem de webhooks	`300/min`
Criação de checkout e criação de webhooks	`60/min`

Há ainda um teto global de 600 requisições por minuto por IP, aplicado antes da autenticação. Ao exceder qualquer limite, a API responde 429 RATE_LIMIT_EXCEEDED com o header Retry-After.

Rastreamento

X-Request-Id: toda resposta inclui o header X-Request-Id. Envie esse header na requisição para correlacionar logs com o suporte; se ausente, a API gera um valor automaticamente.