GG CheckoutCentral de Ajuda

Erros e limites

Os erros da API de pagamentos vêm em um formato único, com um código estável, e cada chave tem limites de requisições por minuto.

Os erros da API de pagamentos vêm sempre no mesmo formato, com o status HTTP, um tipo e um código estável que identifica a causa. Os limites de requisição definem quantas cobranças cada chave e cada conta podem criar, consultar e cancelar por minuto.

Formato do erro

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_buyer_document",
    "message": "buyer.document is not a valid CPF or CNPJ.",
    "param": "buyer.document",
    "request_id": "req_9f2c…"
  }
}
CampoO que traz
typeO grupo do erro.
codeO código do erro. É estável e identifica a causa.
messageA descrição em texto, que pode mudar.
paramO campo do pedido que causou o erro, quando houver.
request_idO identificador da requisição, também enviado no header Request-Id. O suporte usa esse valor para localizar a requisição.

Códigos

HTTPtypecodeCausa
400invalid_requestinvalid_json, invalid_wallet, amount_too_small, amount_too_large, description_too_long, invalid_buyer_name, invalid_buyer_email, invalid_buyer_document, invalid_buyer_phone, invalid_buyer_ip, invalid_metadata, invalid_external_reference, invalid_status, invalid_cursor, invalid_created_gteO campo indicado em param é inválido.
400idempotencyidempotency_key_required, invalid_idempotency_keyFalta o header Idempotency-Key, ou o valor é inválido.
401authenticationmissing_api_key, invalid_api_key, api_key_revoked, api_key_expiredA chave falta, é inválida, foi revogada ou expirou. A chave antiga de uma troca expira no fim do prazo escolhido.
402gatewaypix_generation_failedNenhum gateway da ordem de cobrança conseguiu gerar o Pix.
403permissionwallet_not_allowed_for_keyA chave não tem acesso a essa ordem de cobrança.
403permissionip_not_allowedO IP do servidor não está na lista de IPs permitidos da chave.
403permissionaccount_suspendedA conta está suspensa.
404invalid_requestintent_not_found, wallet_not_found, route_not_foundO ID ou a rota não existe. Cobranças de ordens fora do escopo da chave também retornam intent_not_found.
405invalid_requestmethod_not_allowedO método HTTP não vale para a rota.
409idempotencyidempotency_key_reusedA mesma Idempotency-Key foi usada com outro corpo.
409idempotencyrequest_in_progressO pedido anterior com a mesma chave ainda está em andamento.
409invalid_requestexternal_reference_takenJá existe uma cobrança aberta ou paga com essa referência.
409invalid_requestintent_not_cancelableA cobrança já foi paga ou já terminou.
413invalid_requestbody_too_largeO corpo do pedido passou do tamanho aceito, por exemplo no metadata.
415invalid_requestunsupported_media_typeFalta o header Content-Type: application/json.
422invalid_requestwallet_has_no_active_pixA ordem de cobrança não tem nenhum gateway de Pix ativo.
429rate_limitrate_limit_exceededO limite de requisições foi atingido. O header Retry-After informa quantos segundos esperar.
500internalinternal_errorErro interno. O pedido pode ser repetido com a mesma Idempotency-Key.
502gatewaygateway_unavailableO gateway não respondeu. O pedido pode ser repetido com a mesma Idempotency-Key, e a cobrança é consultada antes da nova tentativa, sem duplicar.
503internalrate_limiter_unavailableO controle de limites está indisponível. O pedido pode ser repetido em instantes.

Qualquer outro erro 4xx vem com type: invalid_request.

Limites de requisição

OperaçãoPor chavePor conta (todas as chaves)
Criar cobrança60 por minuto120 por minuto
Consultar300 por minuto
Cancelar60 por minuto

Acima do limite, a API responde 429 rate_limit_exceeded, com o header Retry-After. As chaves de teste têm limites próprios, menores, descritos em Modo de teste.

Valor por cobrança

O valor mínimo de uma cobrança é R$ 1,00. O valor máximo é o limite da conta, de R$ 5.000,00 por padrão, ou o Valor máximo por cobrança da chave, quando ele é menor. Limites maiores são pedidos ao suporte.

Páginas relacionadas

Nesta página