Erros

Envelopes de erro estáveis para todos os endpoints REST.

Erros públicos retornam type, code, message segura e request_id. O request id deve ser logado por integradores e times de suporte.

Envelope de erro

{  "error": {    "type": "validation_error",    "code": "invalid_request",    "message": "Invalid request payload.",    "request_id": "req_xxx",    "issues": []  }}

Tipos de erro

Campo	Tipo	Descrição
`authentication_error`	401	API key ausente, malformada ou inválida.
`permission_error`	403	A chave é válida, mas não tem a permissão necessária.
`validation_error`	400	Body, path ou query parameters inválidos.
`idempotency_error`	409	A Idempotency-Key foi reutilizada com outra requisição.
`not_found_error`	404	O recurso não existe no escopo da API key atual.
`rate_limit_error`	429	A integração excedeu o rate limit configurado.
`configuration_error`	400	A configuração da plataforma está incompleta para esta operação.
`api_error`	5xx	Falha inesperada da plataforma ou downstream.

Códigos comuns

Campo	Tipo	Descrição
`invalid_api_key`	auth	Header Authorization ausente ou inválido.
`insufficient_permissions`	authz	A chave não pode executar esta ação.
`invalid_request`	validation	O payload falhou na validação de schema.
`raw_card_not_allowed`	PCI	Dados brutos de cartão enviados para endpoint que não tokeniza.
`pricing_plan_not_configured`	config	A plataforma ainda não configurou o plano de taxas para este método/parcelamento.
`idempotency_key_conflict`	retry	A mesma chave foi usada para uma operação diferente.
`internal_error`	server	Falha inesperada; use request_id ao acionar suporte.