Formato de Erro
Quando uma requisição falha, a API retorna um objeto com a seguinte estrutura:{
"message": "Cobrança não encontrada",
"error": "CHARGE_NOT_FOUND",
"status": 404
}
| Campo | Tipo | Descrição |
|---|---|---|
message | string | Mensagem descritiva em português |
error | string | Código de erro programático em inglês |
status | number | Código HTTP da resposta |
Códigos HTTP
| Código | Significado | Descrição |
|---|---|---|
200 | OK | Requisição bem-sucedida |
201 | Created | Recurso criado com sucesso |
400 | Bad Request | Dados inválidos ou parâmetros ausentes |
401 | Unauthorized | Autenticação ausente ou inválida |
403 | Forbidden | Sem permissão para acessar o recurso |
404 | Not Found | Recurso não encontrado |
409 | Conflict | Conflito (recurso já existe) |
422 | Unprocessable Entity | Erro de validação nos dados enviados |
429 | Too Many Requests | Limite de requisições excedido |
500 | Internal Server Error | Erro interno do servidor |
Códigos de Erro Comuns
Autenticação
| Código | Descrição |
|---|---|
UNAUTHORIZED | Autenticação ausente, token/chave inválida ou IP fora da whitelist |
INSUFFICIENT_PERMISSION | Sem permissão para a ação solicitada |
NO_ACTIVE_MERCHANT | Nenhum merchant ativo selecionado |
API_KEY_REVOKED | Chave de API foi revogada |
Rate Limiting
| Código | Descrição |
|---|---|
RATE_LIMIT_EXCEEDED | Limite de requisições excedido |
Recursos
| Código | Descrição |
|---|---|
NOT_FOUND | Recurso não encontrado |
MERCHANT_ID_REQUIRED | ID do merchant é obrigatório |
CHARGE_NOT_FOUND | Cobrança não encontrada |
WALLET_NOT_FOUND | Carteira não encontrada |
Cobranças
| Código | Descrição |
|---|---|
IDEMPOTENCY_CONFLICT | Já existe uma cobrança com a chave de idempotência informada |
BILLING_ADDRESS_REQUIRED | Endereço de cobrança obrigatório para o método de pagamento informado |
PAYMENT_METHOD_NOT_ALLOWED | Método de pagamento não habilitado para a empresa |
CHARGE_AMOUNT_EXCEEDS_LIMIT | Valor da cobrança excede o limite máximo permitido por transação para a empresa |
THREE_DS_REQUIRED | Autenticação 3DS obrigatória para esta cobrança |
FRAUD_ANALYSIS_REQUIRED | Análise de fraude obrigatória para esta cobrança |
TOKEN_NOT_FOUND | Token de pagamento não encontrado |
NO_ACTIVE_ORCHESTRATOR_FLOW | Nenhum fluxo de orquestração ativo configurado |
ORCHESTRATOR_RESOLUTION_FAILED | Erro interno ao resolver o fluxo de orquestração |
MERCHANT_WALLET_NOT_FOUND | Empresa não possui carteira configurada |
SUBMERCHANT_WALLET_NOT_FOUND | Submerchant não possui carteira configurada |
CHARGE_AUTHORIZATION_FAILED | Pagamento recusado pela adquirente |
CHARGE_FAILED | Falha ao processar a cobrança |
FETCH_FAILED | Falha ao buscar a cobrança |
Captura
| Código | Descrição |
|---|---|
CHARGE_ALREADY_CAPTURED | Cobrança não pode ser capturada no estado atual |
CAPTURE_FAILED | Falha ao capturar a cobrança |
Estorno
| Código | Descrição |
|---|---|
CHARGE_ALREADY_REFUNDED | Cobrança não pode ser estornada no estado atual |
REFUND_AMOUNT_EXCEEDS_CHARGE | Valor do estorno excede o valor da cobrança |
CHARGE_STATE_CHANGED | Estado da cobrança mudou durante o estorno |
REFUND_FAILED | Falha ao estornar a cobrança |
Tratamento de Erros
Recomendamos sempre verificar o campoerror da resposta antes de processar os dados:
const response = await fetch('https://api.accithus.com/v1/charges', {
headers: { 'Authorization': `Basic ${credentials}` },
});
const result = await response.json();
if (result.error) {
console.error(`Erro: ${result.error} - ${result.message}`);
// Trate o erro conforme o código
return;
}
// Processe os dados normalmente
const charges = result.data;