Erros

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 campo error da resposta antes de processar os dados:

const response = await fetch('https://api.payhubrasil.com.br/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;

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 campo error da resposta antes de processar os dados:

const response = await fetch('https://api.payhubrasil.com.br/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;

Formato de Erro

Códigos HTTP

Códigos de Erro Comuns

Autenticação

Rate Limiting

Recursos

Cobranças

Captura

Estorno

Tratamento de Erros

On this page

Erros

Formato de Erro

Códigos HTTP

Códigos de Erro Comuns

Autenticação

Rate Limiting

Recursos

Cobranças

Captura

Estorno

Tratamento de Erros

On this page