Integração
Erros
Todo erro vem no envelope
{ error: { code, message, requestId } }. Mostre a message (já em português), trate pelo code e guarde o requestId.404 significa inexistente ou fora do seu escopo — de propósito, os dois são indistinguíveis.Gerais
| HTTP | code | Significado | O que fazer |
|---|---|---|---|
| 401 | B2B_CREDENTIAL_INVALID | credencial ausente/errada/revogada | conferir clientId/clientSecret |
| 404 | NOT_FOUND | não existe OU não é seu | conferir o externalUserId |
| 400 | VALIDATION_ERROR | corpo ou parâmetro inválido (a mensagem diz qual) | corrigir |
| 400 | IDEMPOTENCY_KEY_REQUIRED | faltou o cabeçalho | enviar Idempotency-Key |
| 409 | IDEMPOTENCY_CONFLICT | mesma chave com outro corpo | nova chave para nova ação |
| 409 | IDEMPOTENCY_IN_PROGRESS | mesma chave ainda processando | repetir com a mesma chave |
| 400 | TENANT_REQUIRED | faltou tenantId | enviar |
| 403 | SCOPE_FIELD_REJECTED | campo controlado pelo FINAUTON | remover o campo |
| 429 | RATE_LIMITED | limite por minuto do parceiro | esperar e repetir com backoff |
Regras de negócio
| HTTP | code | Significado | O que fazer |
|---|---|---|---|
| 403 | PROVIDER_NOT_GRANTED · STRATEGY_NOT_GRANTED | fora do contrato | usar o concedido |
| 403 | STRATEGY_NOT_AVAILABLE | estratégia não publicada | usar GET /v1/strategies |
| 422 | RISK_ENVELOPE_EXCEEDED | acima do limite do contrato | reduzir (o limite vem na mensagem) |
| 422 | RISK_ACK_REQUIRED | faltou confirmar os alertas | prévia + riskAcknowledgement |
| 400 | SETUP_INCOMPLETE | faltam campos para ligar | ver setupStatus.issues |
| 422 | DAILY_LOSS_HALT | trava diária atingida | aguardar o dia seguinte (UTC) |
| 403 | PAPER_NOT_GRANTED | modo simulado não existe no B2B | mode "REAL" |
| 422 | API_NOT_CONFIGURED · CREDENTIALS_MISSING | corretora não conectada | connect-sessions |
| 403 | RETURN_URL_NOT_ALLOWED | returnUrl não registrado | pedir registro ao FINAUTON |
| 403 | CLIENT_SUSPENDED | ação exige cliente ativo | reativar |
| 503 | PROVIDER_DOWN | corretora indisponível | tentar depois; não duplicar |
Pagamento
| HTTP | code | Significado | O que fazer |
|---|---|---|---|
| 202 | PAYMENT_AWAITING_CONFIRMATIONS | aguardando confirmações | reenviar o mesmo txHash depois |
| 202 | PAYMENT_UNDERPAID | valor abaixo do exato: não creditado | gerar nova instrução / falar com o FINAUTON |
| 202 | PAYMENT_WRONG_SENDER · _WRONG_TOKEN_OR_RECIPIENT · _WRONG_NETWORK · _TX_NOT_FOUND | verificação on-chain não confere | conferir rede, token, destinatário, pagador e valor |
| 200 | PAYMENT_OVERPAID_MANUAL_REVIEW | valor acima: fatura quitada, excedente em revisão manual | nada (o FINAUTON trata) |
| 409 | TX_ALREADY_USED | a transação já pagou outra fatura | nunca reutilizar tx |
| 409 | PAYMENT_EXPIRED | instrução expirou | gerar nova instrução |
| 409 | OBLIGATION_NOT_OPEN | fatura já paga/dispensada | — |
| 400 | NETWORK_NOT_ENABLED · TOKEN_NOT_SUPPORTED | rede/token não aceitos | usar os de billing.payment |