Pular para o conteúdo
xFlow Payments
EntrarCriar conta

Glossário

O que são códigos de status HTTP

Códigos de status HTTP são os números de três dígitos que um servidor devolve para dizer o resultado de uma requisição. O primeiro dígito indica a família: 2xx deu certo, 4xx o problema está no pedido e 5xx a falha foi do lado do servidor ou de um sistema que ele chamou.

Atualizado em · Equipe xFlow Payments

Antes de ler o corpo da resposta, o seu código deve olhar o status. Ele diz se dá para usar o resultado, se é preciso corrigir o pedido ou se vale tentar de novo mais tarde. A semântica de cada código está na especificação do HTTP, hoje a RFC 9110.

As cinco famílias

Família Significado O que fazer
1xx Informativo Raramente aparece numa API.
2xx Sucesso Ler o corpo.
3xx Redirecionamento Seguir o novo endereço.
4xx Erro do cliente Corrigir o pedido. Repetir igual não resolve, salvo exceções como o 429.
5xx Erro do servidor Tentar de novo depois, de forma segura.

Na API da xFlow

A documentação da xFlow usa estes códigos:

Status Quando aparece
200 Requisição bem-sucedida.
201 Recurso criado, como uma cobrança ou um saque.
202 Estorno aceito pelo PSP, ainda em processamento.
400 Corpo inválido. O campo details aponta o problema.
401 Chave ausente, inválida ou revogada, ou IP fora da allowlist.
403 Conta em análise ou bloqueada, saque por API desabilitado, recurso indisponível com chave de teste ou simulação chamada com chave de produção.
404 Cobrança ou saque não encontrado.
409 Idempotency-Key reusada com um corpo diferente.
422 Recusa de negócio, como saque sem saldo ou estorno fora do prazo.
429 Limite de requisições excedido.
502 Falha no provedor ao gerar a cobrança, ou PSP que recusou ou não respondeu ao estorno.

Todo erro volta em JSON com error, message e request_id. O status diz a família. O campo error diz o caso exato, e é nele que o seu código deve decidir o que fazer.

Exemplo

json
{
  "error": "idempotency_conflict",
  "message": "...",
  "request_id": "req_..."
}

Esse 409 não se resolve repetindo: a mesma chave só vale para o mesmo pedido, como explica o verbete de idempotência. Já o 429 pede espera, como mostra o rate limit. A tabela com cada código de erro, a causa e a solução está em erros da API Pix.

Termos relacionados

Continue lendo

BlogErros da API PixNa API Pix da xFlow, todo erro volta em JSON com error (o código), message e request_id. O status HTTP diz a família do problema: 400 corpo inválido, 401 credencial, 403 conta ou modo, 404 recurso inexistente, 409 idempotência, 422 recusa de negócio, 429 limite e 502 falha no provedor. O request_id localiza a chamada em Integrações > Logs da API.GlossárioO que é rate limitRate limit é o limite de requisições que uma API aceita de um mesmo cliente em um intervalo de tempo. Acima dele, a API responde 429 Too Many Requests, e o cliente deve esperar antes de tentar de novo.GlossárioO que é API RESTAPI REST é uma interface que expõe recursos em endereços HTTP e usa os métodos do próprio protocolo, como GET e POST, para consultar e alterar esses recursos. Cada requisição leva tudo o que o servidor precisa para responder, e o resultado volta com um código de status HTTP.GlossárioO que é idempotênciaIdempotência é a propriedade de uma operação que produz o mesmo efeito quando executada uma ou várias vezes. Em uma API de pagamento, é o que garante que repetir uma chamada depois de uma falha de rede não crie uma segunda cobrança nem um segundo saque.DesenvolvedoresA documentação da API de pagamentos Pix da xFlow é aberta e fica em app.xflowpayments.com/docs, com uma versão em texto para assistentes de IA no llms.txt. Esta página reúne o caminho para integrar: chaves, sandbox, webhooks, logs e guias técnicos.