Erros e limites

Envelope de erro

Toda resposta de erro da API pública usa o mesmo envelope:

{
  "error": "idempotency_conflict",
  "message": "Descrição legível opcional do problema."
}

error (obrigatório): código curto/estável — use-o no tratamento programático.
message (opcional): texto legível para logs; pode estar ausente.

O SDK (@hiboupay/api-client) parseia esse envelope e lança HibouPayApiError (com .status, .error, .message) em qualquer resposta não-2xx — ver SDK e Quickstart.

Status codes

Status	Quando	Onde costuma aparecer
`400`	Requisição malformada (JSON inválido, tipos incorretos).	`POST /v1/sessions`
`401`	`X-Api-Key` ausente/inválida.	Endpoints autenticados
`404`	Sessão/recurso não encontrado.	`GET /v1/sessions/{id}`, `POST /v1/sessions/{id}/cancel`
`409`	Conflito: idempotência (mesma `platformPaymentId` com payload divergente) ou status atual não permite a operação (`cancel`).	`POST /v1/sessions`, `POST /v1/sessions/{id}/cancel`
`422`	Corpo sintaticamente válido, mas viola regra de negócio.	`POST /v1/sessions`
`429`	Rate limit excedido.	`POST /v1/sessions`

Consulte a referência Redoc para o detalhamento por endpoint (nem todo endpoint expõe todos os status acima).

Rate limit

Limite atual: 60 requisições por minuto por API key.
Ao exceder, a API responde 429 com o envelope de erro e o header Retry-After (segundos a aguardar).
Limites diferenciados por plano podem existir no futuro; trate o valor acima como o default vigente.

Idempotência

Header: Idempotency-Key, obrigatório em POST /v1/sessions; recomendado em POST /v1/sessions/{id}/cancel.
Chave lógica do create: (merchantId, platformPaymentId) — mesmo payload devolve o resultado original; payload divergente responde 409.
Janela: 24 horas — depois desse período, a mesma chave pode ser reutilizada como operação nova.

Boas práticas

Trate error (código curto) no código; use message só para logs — o texto livre pode mudar.
Em 409 de idempotência no create, verifique se o retry alterou o payload sem trocar a platformPaymentId.
Em 429, respeite o Retry-After — não faça retry imediato em loop apertado.