ITP - Códigos de Resposta HTTP

Visão Geral

Esta página descreve os códigos HTTP retornados pela API de Pix ITP e suas interpretações, incluindo orientações de tratamento para cada cenário.

Códigos de Sucesso

Código	Status	Ocorre em	Descrição
`200 OK`	Sucesso	`GET` e alguns `POST`	Requisição processada com sucesso. Body contém o recurso solicitado
`201 Created`	Criado	`POST /payment-initiation`, `POST /callback`, `POST /pix`	Recurso criado com sucesso

Códigos de Erro do Cliente (4xx)

Código	Status	Causas Comuns	Como Tratar
`400 Bad Request`	Requisição inválida	Body malformado, campo obrigatório ausente, formato de campo incorreto	Revise o payload. Verifique campos obrigatórios, tipos e formatos
`401 Unauthorized`	Não autorizado	`access_token` ausente, expirado ou inválido	Obtenha um novo token via `POST /v5/token`
`403 Forbidden`	Proibido	Aplicação sem permissão para o recurso solicitado	Verifique as permissões do `client_id` com a Celcoin
`404 Not Found`	Não encontrado	`paymentInitiationId` ou `applicationId` inexistente	Verifique se o ID está correto e pertence à mesma aplicação
`409 Conflict`	Conflito	Tentativa de executar `/pix` em consentimento já utilizado	Crie um novo consentimento
`422 Unprocessable Entity`	Entidade não processável	Regra de negócio violada. Body contém array `errors[]` com código e detalhe	Leia o campo `errors[].code` e `errors[].detail` para identificar o problema
`429 Too Many Requests`	Limite de taxa excedido	Muitas requisições em janela de tempo	Implemente backoff exponencial. Aguarde antes de tentar novamente

Códigos de Erro do Servidor (5xx)

Código	Status	Descrição	Como Tratar
`500 Internal Server Error`	Erro interno	Falha inesperada no servidor	Tente novamente após alguns segundos. Se persistir, acione o suporte
`502 Bad Gateway`	Gateway inválido	Erro de comunicação com serviço interno ou detentora	Tente novamente. Pode ser falha temporária
`503 Service Unavailable`	Serviço indisponível	Manutenção programada ou instabilidade	Aguarde e tente novamente. Consulte status page
`504 Gateway Timeout`	Timeout de gateway	A detentora não respondeu no prazo	Consulte status via `GET /payment-initiation/:id` antes de tentar novamente

Estrutura de Erro 422

Erros 422 retornam um array de erros com código, título e detalhe:

{
  "errors": [
    {
      "code": "DATA_PAGAMENTO_INVALIDA",
      "title": "Data de pagamento inválida.",
      "detail": "Data de pagamento inválida para a forma de pagamento selecionada."
    }
  ]
}

Campo	Descrição
`errors[].code`	Código de erro legível por máquina — use para lógica de tratamento
`errors[].title`	Título curto do erro em português
`errors[].detail`	Descrição detalhada do problema

Tabela de Códigos de Erro de Negócio (422)

`code`	Descrição	Causa
`DATA_PAGAMENTO_INVALIDA`	Data de pagamento inválida	Data passada ou formato incorreto
`CONSENTIMENTO_INVALIDO`	Consentimento inválido	Status incompatível com a operação
`PAGAMENTO_JA_EXECUTADO`	Pagamento já foi executado	Tentativa de chamar `/pix` em consentimento `CONSUMED`
`BRAND_NAO_ENCONTRADA`	Marca não encontrada	`brandId` inexistente ou inativo
`CPF_CNPJ_INVALIDO`	CPF/CNPJ inválido	Documento do creditor com formato incorreto
`VALOR_INVALIDO`	Valor inválido	Formato do `amount` incorreto
`PROXY_INVALIDO`	Chave Pix inválida	`proxy` com formato incorreto para o `localInstrument` informado

Boas Práticas de Tratamento de Erros

Para 401: Implemente renovação automática do token antes de retentar. Nunca exiba erros de autenticação ao usuário final.

Para 422: Leia sempre errors[].code. Exiba mensagens amigáveis baseadas no código — não mostre o detail técnico diretamente ao usuário.

Para 429: Use backoff exponencial: aguarde 1s, depois 2s, depois 4s. Limite a 3 tentativas.

Para 5xx: Não retente imediatamente — pode agravar o problema. Aguarde pelo menos 5 segundos antes de uma nova tentativa.

Para 504: Antes de retentar a operação, consulte o status do pagamento via GET /payment-initiation/:id para verificar se a operação foi processada, evitando duplicidade.

Updated about 2 hours ago