Catálogo de erros da API v1

Todo erro sob /v1 segue a RFC 9457 (application/problem+json). O type aponta para {APP_URL}/errors/{code}, e cada seção abaixo é o conteúdo de uma dessas páginas (M5.4). Formato e membros do problema: referência da API.

Regra para o integrador: decida pelo code (estável, em inglês). O title é fixo por code, mas o detail pode mudar de texto. Guarde sempre o request_id: com ele o suporte acha a requisição no log.

O title e o detail abaixo são os que o código devolve hoje. "Sem detail" quer dizer que o problema sai só com o title.

Implementados

O /oauth/token não usa este formato: ele responde no padrão OAuth2 (ver abaixo).

idempotency_key_required

Quando acontece: um POST sob /v1 (criar ou cancelar pagamento) chegou sem o header Idempotency-Key, ou com ele vazio.

O que fazer: gere uma chave por operação (um UUID serve), guarde-a antes de enviar e mande-a no header. Ver idempotência.

idempotency_key_invalid

Quando acontece: a Idempotency-Key tem mais de 255 caracteres.

O que fazer: use uma chave curta. Um UUID (36 caracteres) é o recomendado.

bad_request

Quando acontece: o framework recusou a requisição com um status 4xx que não tem código próprio nesta lista.

O que fazer: confira método, rota, headers e corpo. Se não achar o motivo, mande o request_id ao suporte.

unauthenticated

Quando acontece: sem Authorization: Bearer …; token inválido ou expirado (vale 1 h); client revogado no painel; client sem tenant dono.

O que fazer: peça um token novo em POST /oauth/token e repita a chamada. Se continuar, confira se o client não foi revogado. Renove o token antes de expirar (expires_in) em vez de esperar o 401.

ip_not_allowed

Quando acontece: o token é válido, mas a requisição saiu de um IP fora da lista de IPs permitidos do tenant. Lista vazia bloqueia tudo.

O que fazer: cadastre no painel, em "Acesso à API", o IP de saída do seu servidor (ou a faixa CIDR) que aparece no detail. Atenção ao IP de saída real: NAT, proxy e balanceador mudam o IP que chega ao Pagaki.

forbidden

Quando acontece: reservado. A API v1 não tem escopos nem permissões por recurso no MVP, então nenhuma rota de hoje devolve este código; ele existe para quando houver.

O que fazer: se receber, mande o request_id ao suporte.

not_found

Quando acontece: a rota não existe, ou o recurso não existe, tem o ID mal formado (prefixo errado, tamanho errado) ou é de outro tenant. Por segurança, as três situações do recurso respondem igual.

O que fazer: confira o ID completo, com o prefixo (pay_…), e se você está no ambiente certo: um pagamento do sandbox não existe na produção.

method_not_allowed

Quando acontece: a rota existe, mas não com esse método (por exemplo, DELETE /v1/payments/{id}).

O que fazer: use o método da referência. Para cancelar um PIX, é POST /v1/payments/{id}/cancel.

idempotency_key_in_progress

Quando acontece: outra requisição com a mesma Idempotency-Key ainda está em execução (por exemplo, você repetiu a criação antes de a primeira terminar).

O que fazer: espere alguns segundos e repita com a mesma chave e o mesmo corpo: quando a primeira terminar, você recebe a resposta dela. Se o processo do Pagaki tiver caído no meio, a chave é liberada depois de 60 s.

invalid_state

Quando acontece: POST /v1/payments/{id}/cancel num pagamento que não está em pending (já pago, expirado, cancelado, falho ou ainda em processing). O mesmo código sai em retry e cancel de um bill_payment fora do status permitido, com o title "Estado não permite a operação".

O que fazer: consulte o pagamento (GET /v1/payments/{id}) e decida pelo status atual. Um pagamento em processing só pode ser cancelado depois de virar pending. A resposta fica guardada na chave: para tentar de novo, use outra Idempotency-Key.

conflict

Quando acontece: reservado para conflitos genéricos do framework. Nenhuma rota de hoje devolve este código de propósito.

O que fazer: consulte o recurso e repita. Se continuar, mande o request_id ao suporte.

validation_failed

Quando acontece: o corpo do POST /v1/payments ou os parâmetros de GET /v1/payments não passam na validação: campo obrigatório ausente, method diferente de pix, amount não inteiro ou menor que 1, expires_at no passado, CPF/CNPJ inválido, metadata com mais de 20 chaves, chave maior que 40 ou valor que não é texto, gateway que não é um inst_…, limit fora de 1 a 100.

O problema traz errors, com o nome do campo (com ponto nos aninhados) e as mensagens:

{ "errors": { "payer.document": ["O payer.document precisa ser um CPF ou CNPJ válido."], "amount": ["The amount field must be an integer."] } }

O que fazer: corrija os campos apontados e reenvie. Este erro não fica guardado na Idempotency-Key: pode reenviar com a mesma chave. As mensagens são para gente ler e hoje saem em inglês nas regras do framework; decida pelo nome do campo, nunca pelo texto.

idempotency_key_reused

Quando acontece: a chave já foi usada nas últimas 24 h com outro corpo ou em outra rota (por exemplo, a chave da criação reaproveitada no cancelamento).

O que fazer: é quase sempre um erro de integração. Gere uma chave por operação lógica. Se a intenção era repetir a mesma operação, mande o corpo idêntico ao original.

no_gateway_available

Quando acontece: antes de criar qualquer coisa, o roteador não achou nenhuma instalação de gateway que atenda o pedido: nenhuma instalação ativa para PIX; o prazo até expires_at é menor que o mínimo dos gateways (hoje 60 s); o gateway forçado não existe, está inativo ou não atende. Nenhum pagamento é criado e o corpo não traz payment.

O que fazer: confira no painel se há instalação ativa; use um expires_at de pelo menos alguns minutos; se forçou um gateway, confira o inst_…. A resposta fica guardada na chave: para tentar de novo, use outra Idempotency-Key.

gateway_invalid_data

Quando acontece: o gateway recusou os dados da cobrança (por exemplo, documento ou e-mail que ele não aceita). Não há fallback: outro gateway recusaria o mesmo dado. O problema traz payment, com status: failed, e sai o webhook payment.failed.

O que fazer: corrija os dados do pagador e crie um pagamento novo, com outra Idempotency-Key. O pagamento failed fica como registro.

cancel_not_supported

Quando acontece: o pagamento está em pending, mas o gateway que ficou com a cobrança não oferece cancelamento. Asaas e Efí cancelam, então hoje isso só acontece com um gateway novo sem essa capacidade.

O que fazer: deixe o PIX expirar (o expires_at continua valendo e sai payment.expired). Não mostre mais o QR ao pagador.

rate_limited

Quando acontece: o tenant passou do limite por minuto do plano (standard 600, premium 3.000; valores provisórios). O limite é do tenant inteiro, somando todos os clients e rotas.

O que fazer: espere os segundos do header Retry-After e repita. Acompanhe X-RateLimit-Remaining para não chegar no limite. Não faça polling de status: use os webhooks. A requisição barrada não reservou a Idempotency-Key, então pode repetir com a mesma.

internal_error

Quando acontece: um erro inesperado do Pagaki. A mensagem interna nunca é exposta; o erro é registrado com o request_id.

O que fazer: repita com a mesma Idempotency-Key: o 500 não fica guardado, e se a operação chegou a ser feita você recebe a resposta dela. Se persistir, mande o request_id ao suporte.

gateway_rejected

Quando acontece: o gateway recusou a cobrança por regra de negócio dele (recusa definitiva). Não há fallback: tentar outro gateway não mudaria a decisão. Hoje os conectores do Asaas e da Efí classificam as recusas de PIX como gateway_invalid_data; este código existe para recusas de negócio (como cartão negado, F4). O problema traz payment, com status: failed, e sai o webhook payment.failed.

O que fazer: não repita igual. Leia o detail; se der para corrigir, crie um pagamento novo com outra Idempotency-Key. A resposta fica guardada na chave usada.

gateway_failure

Quando acontece:

• Na criação: todos os gateways candidatos falharam (indisponíveis, limite atingido, credencial inválida, resposta desconhecida) e o Pagaki já fez o fallback. O problema traz payment, com status: failed, e sai payment.failed.

• No cancelamento: o gateway não confirmou o cancelamento. O pagamento continua pending e o problema não traz payment.

• Na simulação da conta (pay_bill): o gateway não respondeu; nada foi criado e o problema não traz payment.

O que fazer: na criação, crie um pagamento novo com outra Idempotency-Key depois de alguns segundos. No cancelamento, repita o cancelamento com outra Idempotency-Key (o 502 fica guardado na chave usada). Em ambos, o attempts[] do pagamento mostra o que cada gateway respondeu.

amount_mismatch

Quando acontece: pay_bill.amount é diferente do valor que a simulação leu no gateway. Na criação nada é criado. O mesmo valor aparece em bill_payment.failure.code quando a divergência surge na simulação logo antes de pagar.

O que fazer: confira a guia (juros, multa, desconto) ou envie sem pay_bill.amount, que é só para conferência.

amount_insufficient

Quando acontece: o amount enviado não cobre a conta, as tarifas e o service_fee, ou o amount de um retry passa do valor da conta que o pagamento cobriu.

O que fazer: envie sem amount, para o Pagaki calcular, ou use o valor de POST /v1/payments/quote. Ver PIX com pagamento de conta.

fees_not_configured

Quando acontece: o gateway não informou a tarifa de receber nem a de pagar a conta, e a instalação não tem a tarifa cadastrada. O Pagaki não chuta tarifa.

O que fazer: cadastre a tarifa da instalação no painel, ou confira se a credencial tem acesso às tarifas da conta no gateway.

invalid_identification_field

Quando acontece: a linha do pay_bill ou do retry não tem 47 dígitos (boleto) nem 48 (guia de arrecadação, começando em 8), ou os dígitos verificadores não batem.

O que fazer: confira a leitura da linha digitável. Pontos e espaços são aceitos; o código de barras de 44 dígitos não.

bill_overdue

Quando acontece: o due_date do pay_bill ou do retry está no passado, no dia de São Paulo. É regra do Pagaki: o Asaas aceita boleto vencido quando o emissor permite.

O que fazer: reemita a guia ou o boleto com vencimento válido e use a linha digitável nova.

bill_payment_not_supported

Quando acontece: o pedido tem pay_bill, mas nenhuma instalação ativa paga contas (capacidade PaysBills; no MVP, só o Asaas), ou o gateway forçado não tem essa capacidade.

O que fazer: confira no painel se a instalação do Asaas está ativa e habilitada para o Pague Contas; se forçou um gateway, use a instalação do Asaas.

Erros do /oauth/token

O endpoint de token segue o OAuth2 (RFC 6749), não a RFC 9457:

{ "error": "invalid_client", "error_description": "Client authentication failed", "message": "Client authentication failed" }

Planejados

Estes códigos ainda não saem do código. Entram com a etapa indicada.

amount_exceeds_refundable

Planejado 422. title: Valor acima do saldo estornável.

Quando vai acontecer: POST /v1/payments/{id}/refunds com amount maior que amount_paid - amount_refunded.

O que fazer: consulte o pagamento e peça no máximo o saldo restante, ou omita amount para estornar tudo o que sobra.

Retirado: expiration_not_supported

A versão anterior do contrato previa este código para um expires_at que nenhum gateway aceita. No código, essa situação é 422 no_gateway_available, e assim fica no contrato do MVP.