Catálogo de Erros, Throne API

401 credentials_required AUTH

Header Authorization: Bearer pk_xxx:sk_xxx ausente ou vazio.

Resolução

Adicione header Authorization: Bearer {public_key}:{secret_key}
Public key começa com pk_live_ ou pk_test_
Secret key começa com sk_live_ ou sk_test_
Separar por :, NÃO base64 encode

Sample fix, Curl

curl https://api.thronecorporate.com/api/v1/balance \
  --header 'Authorization: Bearer pk_live_xxx:sk_live_xxx'

401 invalid_credentials AUTH

API key inválida, revogada, ou seller suspenso/banido.

Resolução

Confira pk + sk no painel /painel/integracao
Se key rotacionada, old key funciona 7 dias, use new
Se seller suspended/banned, entre em contato suporte
Após 5 tentativas falhas em 5min, IP é flagged como FraudEvent HIGH

401 ip_not_allowed AUTH

IP da request não está no allowlist da API key.

Resolução

Adicione IP no painel /painel/integracao/{key}/ip-allowlist
Para remover restrição, deixe campo vazio (permite qualquer IP)
Cuidado, IP allowlist é proteção crítica, só remover em dev

422 validation_failed VALIDAÇÃO

Request body não passou na validação, veja details pra fields específicos.

Response exemplo

{
  "error": "validation_failed",
  "message": "Os dados fornecidos não são válidos.",
  "details": {
    "amount_cents": ["O valor deve ser maior que 0"],
    "payer_cpf": ["CPF inválido"]
  },
  "request_id": "req_a3b6e3f8"
}

Resolução

Inspecione details, arruma fields apontados
amount_cents, integer, min:1, max:5_000_000
payer_cpf, 11 digits sem máscara
payer_email, valid email format

422 idempotency_key_conflict VALIDAÇÃO

Idempotency-Key usada anteriormente com body diferente, conflito.

Resolução

Use UUID v4 novo pra cada operação distinta
Mesma key + mesmo body, returns cache (24h TTL)
Mesma key + body diferente, 422 (proteção contra accidental change)

403 seller_not_approved NEGÓCIO

Seller status diferente de approved, não pode operar.

Status possíveis

pending, cadastro incompleto, finalize docs KYC
documents_review, aguardando análise KYC
approved, operacional, sem este erro
suspended, contate suporte
banned, operação bloqueada permanentemente

402 insufficient_balance NEGÓCIO

Saldo disponível insuficiente para operação (saque, refund, etc).

Resolução

Consulte saldo, GET /v1/balance
balance_cents = livre, pending_balance_cents = aguardando settle
Para saque, disponível = balance_cents (não pending)

429 rate_limit_exceeded RATE LIMIT

Excedeu limite de requisições por minuto.

Headers de rate limit

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1715722800
Retry-After: 25

Resolução

Aguarde Retry-After segundos antes de re-tentar
Use exponential backoff em produção
Limites, GET 100/min, POST 60/min, PIX create 30/min
Enterprise tier, contate suporte pra boost

500 internal_error INFRA

Erro interno, provavelmente bug Throne, reportado automaticamente Sentry.

Resolução

Inclua request_id no email pro suporte
Confira /up/detailed status sistema
Operações com Idempotency-Key são seguras pra retry
SLA, 99.9% uptime garantido

502 acquirer_error INFRA

Adquirente (Asaas/EfiPay/MP/etc) retornou erro, ou está fora do ar.

Resolução

Multi-acquirer routing automático, Throne tenta fallback se primary down
Confira status adquirentes, /admin/acquirers (admin only)
Aguarde 30s + retry, provavelmente intermitente
Erro persistente, contate suporte com request_id