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…"
}
}| Campo | O que traz |
|---|---|
type | O grupo do erro. |
code | O código do erro. É estável e identifica a causa. |
message | A descrição em texto, que pode mudar. |
param | O campo do pedido que causou o erro, quando houver. |
request_id | O identificador da requisição, também enviado no header Request-Id. O suporte usa esse valor para localizar a requisição. |
Códigos
| HTTP | type | code | Causa |
|---|---|---|---|
| 400 | invalid_request | invalid_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_gte | O campo indicado em param é inválido. |
| 400 | idempotency | idempotency_key_required, invalid_idempotency_key | Falta o header Idempotency-Key, ou o valor é inválido. |
| 401 | authentication | missing_api_key, invalid_api_key, api_key_revoked, api_key_expired | A chave falta, é inválida, foi revogada ou expirou. A chave antiga de uma troca expira no fim do prazo escolhido. |
| 402 | gateway | pix_generation_failed | Nenhum gateway da ordem de cobrança conseguiu gerar o Pix. |
| 403 | permission | wallet_not_allowed_for_key | A chave não tem acesso a essa ordem de cobrança. |
| 403 | permission | ip_not_allowed | O IP do servidor não está na lista de IPs permitidos da chave. |
| 403 | permission | account_suspended | A conta está suspensa. |
| 404 | invalid_request | intent_not_found, wallet_not_found, route_not_found | O ID ou a rota não existe. Cobranças de ordens fora do escopo da chave também retornam intent_not_found. |
| 405 | invalid_request | method_not_allowed | O método HTTP não vale para a rota. |
| 409 | idempotency | idempotency_key_reused | A mesma Idempotency-Key foi usada com outro corpo. |
| 409 | idempotency | request_in_progress | O pedido anterior com a mesma chave ainda está em andamento. |
| 409 | invalid_request | external_reference_taken | Já existe uma cobrança aberta ou paga com essa referência. |
| 409 | invalid_request | intent_not_cancelable | A cobrança já foi paga ou já terminou. |
| 413 | invalid_request | body_too_large | O corpo do pedido passou do tamanho aceito, por exemplo no metadata. |
| 415 | invalid_request | unsupported_media_type | Falta o header Content-Type: application/json. |
| 422 | invalid_request | wallet_has_no_active_pix | A ordem de cobrança não tem nenhum gateway de Pix ativo. |
| 429 | rate_limit | rate_limit_exceeded | O limite de requisições foi atingido. O header Retry-After informa quantos segundos esperar. |
| 500 | internal | internal_error | Erro interno. O pedido pode ser repetido com a mesma Idempotency-Key. |
| 502 | gateway | gateway_unavailable | O 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. |
| 503 | internal | rate_limiter_unavailable | O 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ção | Por chave | Por conta (todas as chaves) |
|---|---|---|
| Criar cobrança | 60 por minuto | 120 por minuto |
| Consultar | 300 por minuto | |
| Cancelar | 60 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
- Idempotência: como repetir um pedido depois de um erro
500ou502. - Chaves da API: os IPs permitidos e o valor máximo de cada chave.
- Falando com o suporte: os canais de atendimento do ggCheckout.
Modo de teste
A chave de teste da API de pagamentos simula a cobrança Pix sem chamar gateway. O resultado é definido pelo valor e pelo documento enviados.
Referência da API
As cinco rotas da API de pagamentos do ggCheckout: criar, consultar, listar e cancelar cobranças Pix e listar as ordens de cobrança da chave.