Tratamento de erros

A API usa códigos de status HTTP convencionais e retorna um corpo JSON padronizado com detalhes do erro.

Formato do erro

{
  "timestamp": "2026-07-18T14:30:00Z",
  "status": 400,
  "code": "BAD_REQUEST",
  "message": "Selecione ao menos um scope para a chave",
  "path": "/api-keys"
}

Erros de validação de campos incluem a lista errors, com um item por campo inválido:

{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "errors": [
    { "field": "amount", "message": "deve ser maior que ou igual a 0.01" },
    { "field": "customerEmail", "message": "deve ser um endereço de e-mail bem formado" }
  ]
}

Códigos de erro

HTTP	code	Significado
400	BAD_REQUEST	Requisição inválida pela regra de negócio
400	VALIDATION_ERROR	Campos inválidos — veja a lista errors
400	INVALID_PARAMETER	Parâmetro de URL ou query com tipo inválido
401	UNAUTHORIZED	Chave de API ausente, inválida, revogada ou expirada
403	FORBIDDEN	A chave não tem o escopo necessário para a operação
404	NOT_FOUND	Recurso não encontrado
409	CONFLICT	Conflito de estado — por exemplo, cancelar um pagamento já confirmado
500	INTERNAL_ERROR	Erro interno da OrcaPay

Recomendações

• Trate erros 5xx com retry exponencial e limite de tentativas; não repita automaticamente erros 4xx.
• Use sempre o campo code de forma programática — as mensagens (message) podem mudar sem aviso.
• Em erros de pagamento (PIX, cartão), o message é uma descrição amigável já traduzida para exibição ao cliente final — não faça parsing dela para tomar decisões de negócio.
• Em erros VALIDATION_ERROR, apresente ao usuário os campos apontados em errors[].field.
• Registre o corpo completo do erro nos seus logs para facilitar o diagnóstico junto ao suporte da OrcaPay.