Conceitos
Erros
Todo erro tem o mesmo formato, com um código estável para o seu programa e uma mensagem em português para pessoas.
Formato
{
"code": "INVALID_REQUEST",
"message": "Requisição inválida.",
"requestId": "req_01JDY9D1B2C3D4E5F6G7H8J9KN",
"fieldErrors": [
{
"field": "amountCents",
"code": "INVALID_FORMAT"
}
]
}| Campo | Descrição |
|---|---|
code | Código estável em MAIÚSCULAS_COM_SUBLINHADO. Programe contra ele, nunca contra a mensagem. |
message | Texto em português para exibir ou registrar. Pode mudar. |
requestId | Identificador da requisição (também no header x-request-id). Informe ao suporte. |
fieldErrors | Opcional. Lista de { field, code } com o caminho do campo inválido (ex.: events.0). |
Erros do provedor de pagamentos nunca são repassados crus: a API traduz para códigos próprios e nunca devolve dados de cartão.
Códigos frequentes
| HTTP | code | Quando |
|---|---|---|
| 400 | INVALID_REQUEST | Corpo, parâmetro ou header inválido. fieldErrors aponta cada campo. |
| 400 | IDEMPOTENCY_KEY_REQUIRED | Mutação sem Idempotency-Key. |
| 401 | INVALID_API_KEY | Chave ausente, malformada, desconhecida ou de outro ambiente. |
| 401 | API_KEY_REVOKED / API_KEY_EXPIRED | Chave revogada ou expirada. |
| 403 | SCOPE_MISSING | A chave não tem o escopo da rota. |
| 403 | ACCOUNT_NOT_ALLOWED | X-Account-Id ausente ou não permitido para a chave. |
| 403 | ACCOUNT_SUSPENDED | Novas operações suspensas para a conta; consultas continuam. |
| 404 | RESOURCE_NOT_FOUND | Não existe nesta conta (inclusive recurso de outra conta). |
| 409 | IDEMPOTENCY_CONFLICT | A Idempotency-Key já foi usada com outro conteúdo. |
| 409 | REQUEST_IN_PROGRESS | A primeira requisição com a mesma chave ainda está em andamento. |
| 409 | CUSTOMER_REFERENCE_CONFLICT / ORDER_REFERENCE_CONFLICT | Já existe cliente ou pedido com a mesma referência externa e outro conteúdo. |
| 409 | PAYMENT_ALREADY_OPEN | Já existe cobrança em aberto ou em processamento para o pedido. |
| 409 | VERSION_CONFLICT | expectedVersion não é a versão atual do recurso: consulte de novo e decida. |
| 409 | SCHEDULE_CHANGED / TERMS_CHANGED | O calendário ou os termos aceitos não são os exibidos agora: mostre de novo e colha novo aceite. |
| 409 | PAYMENT_NOT_READY | QR Pix ainda não disponível: a operação não concluiu. |
| 409 | WEBHOOK_ENDPOINT_NOT_ACTIVE | Endpoint pausado ou desativado: reative antes de reenviar ou testar. |
| 422 | CAPABILITY_UNAVAILABLE | Meio de pagamento indisponível para a conta (veja /v1/accounts/capabilities). |
| 422 | MODE_NOT_AVAILABLE | Modalidade pedida na sessão de checkout indisponível para a conta. |
| 422 | REFUND_EXCEEDS_ELIGIBLE | Estorno acima do elegível (pago − devolvido − reservado). |
| 422 | INSUFFICIENT_AVAILABLE_BALANCE | Estorno de cobrança recebida acima do saldo disponível conciliado. |
| 422 | PAYMENT_NOT_REFUNDABLE | Cobrança pendente, em disputa ou já estornada por inteiro. |
| 422 | TRANSFER_EXCEEDS_ELIGIBLE | Transferência acima do saldo que pode sair agora. |
| 422 | FEE_EXCEEDS_NET_AMOUNT | A tarifa da plataforma ultrapassa o líquido estimado da cobrança. |
| 422 | WEBHOOK_ENDPOINT_LIMIT | A conta já tem 10 endpoints de webhook. |
| 429 | TOO_MANY_REQUESTS | Limite de requisições. Aguarde e repita com a mesma Idempotency-Key. |
| 500 | INTERNAL_ERROR | Erro interno. Numa mutação, o resultado é incerto: repita com a mesma chave. |
Como tratar
- 4xx é conclusivo: a requisição não teve efeito. Corrija e tente de novo.
- 409 REQUEST_IN_PROGRESS, 429 e 5xx pedem repetição com a mesma Idempotency-Key.
- Uma operação
FAILEDtrazerror.codee a próxima ação (nextAction).
import { BusinessRuleError, ConnectionError, IdempotencyConflictError, InvalidRequestError } from "@eclipta-pay/sdk";
try {
await eclipta.createPayment(dados, { idempotencyKey: chaveDaIntencao });
} catch (e) {
if (e instanceof InvalidRequestError) mostrarCampos(e.fieldErrors);
else if (e instanceof BusinessRuleError) avisar(e.code, e.message);
else if (e instanceof IdempotencyConflictError) registrarBug(e.requestId);
else if (e instanceof ConnectionError && e.mayHaveSucceeded) agendarRepeticao(e.idempotencyKey);
else throw e;
}Limite de requisições
Cada chave tem um balde de 100 requisições que se repõe a 100 por segundo (6.000 por minuto). Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset (segundos até o balde encher). Acima do limite a resposta é 429 TOO_MANY_REQUESTS com Retry-After: espere esse tempo e repita com a mesma Idempotency-Key. O SDK faz isso sozinho.