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

200 cautelar_held NEGÓCIO

Transação foi marcada para bloqueio cautelar · seller vê como pending até liberação.

Por que aconteceu

Seller tem cautelar config 1/10 (1 em cada 10 vai pra hold)
TX entrou no ratio determinístico · hold ativo
Saldo retido por cautelar_hold_days ou indefinido
Admin pode revogar manualmente · /admin/cautelar-holds

Não é erro

Status 200 · transaction criada com sucesso. Apenas é hold mode. Para seller, display_status retorna 'pending' até liberação.

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 · held_cents = cautelar
Para saque · disponível = balance_cents (não pending nem held)

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