# Erros URL: https://staging.pagpolar.com/docs/guias/fundamentos/erros > Leia o formato de erro da API, decida o que pode ser repetido e informe o request_id ao suporte. ## Formato do erro Todo erro da API tem o mesmo formato: ```json { "error": { "code": "conflict", "message": "Oferta inativa", "request_id": "3f6c1a52-8e1d-4c0b-9a7e-2d5b6c7e8f90" } } ``` | Campo | O que significa | | ------------ | ------------------------------------------------------------------------ | | `code` | Categoria do erro. Sai do status HTTP. | | `message` | Texto que explica o caso. Use para diferenciar erros com o mesmo `code`. | | `request_id` | Id único da requisição. Informe ao suporte. | > **O code não diz o caso exato** > > Dois erros diferentes com o mesmo status têm o mesmo `code`. Exemplo: "Oferta inativa" e "Oferta expirada" são os dois `409 conflict`. Leia `message` para saber qual aconteceu. ## Códigos | `code` | Status | Quando acontece | Pode repetir? | | --------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `invalid_request` | 400 | Corpo, parâmetro ou header inválido. Regra de negócio, como parcelas acima do limite da oferta. | Não. Corrija a requisição: repetir igual dá o mesmo erro. | | `unauthorized` | 401 | A autenticação falhou. Veja [Erros comuns a todas as rotas](#erros-comuns). | Uma vez, com um token novo. | | `forbidden` | 403 | IP não autorizado na credencial, ou uma regra da conta impede a operação: produto que não permite troca de plano, ou oferta que não está marcada como selecionável pelo cliente. | Não. Corrija a causa. Veja [Trocar de plano](/docs/guias/jornadas/trocar-de-plano). | | `not_found` | 404 | O recurso não existe na sua conta: produto, oferta, venda, assinatura ou cliente. Ou a rota não existe na API. | Não. Confira o id ou o código enviado. Se a mensagem for de rota, veja [Rota inexistente](#rota-inexistente). | | `conflict` | 409 | O estado do recurso impede a operação: oferta inativa ou expirada, meio de pagamento desligado na oferta, ou requisição com a mesma `Idempotency-Key` ainda em processamento. | Só o da `Idempotency-Key`: espere alguns segundos e repita com a mesma chave. Nos outros, ajuste a oferta antes. | | `rate_limit_exceeded` | 429 | Você passou do limite de requisições. | Sim, depois do tempo do header `Retry-After`. | | `sandbox_unavailable` | 502 | Só com a chave de Homologação ou o token dela: o ambiente de testes está fora do ar ou não respondeu em 30 segundos. | Sim, depois de alguns segundos. Veja [Ambiente de testes indisponível](#sandbox-indisponivel). | | `service_unavailable` | 503 | O controle de limite está fora do ar numa rota que movimenta dinheiro. A requisição não foi processada. | Sim, depois de alguns segundos. Nas rotas com `Idempotency-Key`, use a mesma chave. | | `internal_error` | 500 ou maior | Erro inesperado na API. | Com cuidado. Numa rota de cobrança, [procure a venda antes](/docs/guias/fundamentos/idempotencia#erro-nao-garante). | Qualquer `GET` pode ser repetido igual. O `code` é escolhido só pelo status HTTP, com uma exceção: o `502 sandbox_unavailable`. Um status 422 vira `unprocessable_entity`, e qualquer outro status 4xx sem nome na tabela vira `error`. ## Erros comuns a todas as rotas Estes erros podem aparecer em qualquer rota que recebe os dados ou o header citados. Os erros próprios de cada fluxo ficam na página da jornada. | Status | `code` | Quando | O que fazer | | ------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `invalid_request` | Campo obrigatório ausente. `message`: `O campo é obrigatório`, como `O campo customer.email é obrigatório`. | Envie o campo indicado. A mensagem mostra um campo por vez. | | 400 | `invalid_request` | Texto menor ou maior que o permitido. `message`: `O campo deve ter no mínimo 7 caracteres` ou `O campo deve ter no máximo 20 caracteres`. Os números 7 e 20 aparecem qualquer que seja o limite real. Exemplo: `credit_card.cvv`, que aceita 3 ou 4 caracteres, responde com essas mensagens. | Confira o limite do campo na [Referência da API](/docs/referencia), não na mensagem. | | 400 | `invalid_request` | Número fora do limite (como `per_page` acima de 100), URL ou IP inválido, data em formato errado. `message` vazia. | Confira o campo na [Referência da API](/docs/referencia). | | 400 | `invalid_request` | `customer.document` fora do formato. `message`: `Documento inválido: envie o CPF com 11 dígitos ou o CNPJ com 14 dígitos, com ou sem pontuação.` | Veja [Documento e telefone](/docs/guias/fundamentos/valores-datas-e-identificadores#documento-e-telefone). | | 400 | `invalid_request` | `holder_document` fora do formato. `message`: `Documento do titular do cartão inválido: envie o CPF com 11 dígitos ou o CNPJ com 14 dígitos, com ou sem pontuação.` | Veja [Documento e telefone](/docs/guias/fundamentos/valores-datas-e-identificadores#documento-e-telefone). | | 400 | `invalid_request` | `customer.phone` fora do formato. `message`: `Telefone inválido: envie o DDD e o número, com 10 ou 11 dígitos (12 ou 13 com o código do país 55), com ou sem pontuação.` | Veja [Documento e telefone](/docs/guias/fundamentos/valores-datas-e-identificadores#documento-e-telefone). | | 400 | `invalid_request` | `Header Idempotency-Key é obrigatório` ou `Header Idempotency-Key excede 255 caracteres`. | Envie um UUID no header. Veja [Idempotência](/docs/guias/fundamentos/idempotencia). | | 401 | `unauthorized` | Token ausente, fora do formato `Bearer `, expirado ou inválido. Credencial revogada ou expirada. Em `POST /auth/token`, chave ausente ou inválida. | Peça um token novo e repita uma vez, como em [Renove o token no 401](/docs/guias/fundamentos/autenticacao#renovar-no-401). Se continuar, leia a `message` em [Respostas de erro de autenticação](/docs/guias/fundamentos/autenticacao#erros). | | 403 | `forbidden` | `IP não autorizado para esta credencial`. | Autorize o IP na credencial. Veja [Restrição por IP](/docs/guias/fundamentos/autenticacao#restricao-por-ip). | | 409 | `conflict` | `Uma requisição com este Idempotency-Key já está em processamento`. | Espere alguns segundos e repita com a mesma chave. | | 429 | `rate_limit_exceeded` | `Limite de requisições excedido. Aguarde e tente novamente.` | Espere os segundos de `Retry-After` e repita. Veja [Limites de requisição](/docs/guias/fundamentos/limites-de-requisicao). | | 500 | `internal_error` | `Erro interno. Tente novamente ou contate o suporte informando o request_id.` A mensagem é sempre essa em erro 500 ou maior, fora o `502 sandbox_unavailable`. | Guarde o `request_id`. Numa rota de cobrança, [procure a venda antes de repetir](/docs/guias/fundamentos/idempotencia#erro-nao-garante). Se o erro continuar, fale com o suporte. | | 502 | `sandbox_unavailable` | Só com a chave de Homologação ou o token dela: o ambiente de testes está fora do ar ou não respondeu em 30 segundos. | Veja [Ambiente de testes indisponível](#sandbox-indisponivel). | | 503 | `service_unavailable` | `Serviço temporariamente indisponível. Tente novamente em instantes.` Só nas [rotas que movimentam dinheiro](/docs/guias/fundamentos/limites-de-requisicao#resposta-503). | Espere alguns segundos e repita. Nas rotas com `Idempotency-Key`, use a mesma chave. | ## Erros de validação Quando o corpo ou os parâmetros estão errados, a resposta é `400 invalid_request` com **uma** mensagem. Exemplo, ao enviar `offer_identifier` e `offer` juntos: ```json { "error": { "code": "invalid_request", "message": "Envie offer_identifier ou offer, nunca os dois", "request_id": "9b2e7c14-3a5d-4f60-8e1b-7c9d0a2b3c4d" } } ``` A mensagem mostra um problema por vez. Corrija, envie de novo e veja se aparece outro. As mensagens genéricas, inclusive as vazias, estão em [Erros comuns a todas as rotas](#erros-comuns). ## Rota inexistente Quando o método e o caminho não correspondem a nenhuma rota da API, a resposta é `404 not_found`: ```json { "error": { "code": "not_found", "message": "Rota não encontrada na API pública.", "request_id": "5d8e2a61-4b3c-4f7d-9e0a-1c2b3d4e5f60" } } ``` Confira o método e o caminho, e se a URL começa com a URL base `https://api.pagpolar.com/v1`, sem repetir o `/v1`. As rotas existentes estão na [Referência da API](/docs/referencia). O token é conferido antes da rota. Sem token válido, a resposta é `401 unauthorized`, mesmo numa rota que não existe. Com IP fora da lista autorizada, é `403 forbidden`. ## Ambiente de testes indisponível Quando o [ambiente de testes](/docs/guias/fundamentos/ambientes#ambiente-de-testes) está fora do ar ou demora mais de 30 segundos para responder, as chamadas feitas com a chave de Homologação, ou com o token dela, recebem `502`: ```json { "error": { "code": "sandbox_unavailable", "message": "Ambiente de testes indisponível no momento. Tente novamente em instantes.", "request_id": null } } ``` * `request_id` chega `null`, e a resposta não traz o header `X-Request-Id`. * As chaves de Produção não são afetadas. * Quando o ambiente de testes responde, o status e o corpo da resposta dele chegam sem mudança. Os erros seguem o mesmo formato desta página. Espere alguns segundos e repita. Se o erro veio depois de 30 segundos numa rota de cobrança, a venda de teste pode ter sido criada: [procure a venda antes de repetir](/docs/guias/fundamentos/idempotencia#erro-nao-garante). ## Onde encontrar o `request_id` O mesmo valor aparece em dois lugares: * no campo `error.request_id` do corpo do erro; * no header `X-Request-Id` de **toda** resposta da API, inclusive as de sucesso. A única exceção é o `502 sandbox_unavailable`. Grave o `X-Request-Id` nos logs do seu sistema. No painel, o **Histórico de requisições** da credencial mostra o mesmo valor em **ID da requisição**. Veja [Credenciais](/docs/guias/fundamentos/credenciais#historico). ## Próximos passos - [Idempotência](/docs/guias/fundamentos/idempotencia) — Repita uma cobrança sem cobrar duas vezes. - [Limites de requisição](/docs/guias/fundamentos/limites-de-requisicao) — Evite o erro 429.