Erros usam o mesmo envelope, com o código HTTP correspondente:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Dados inválidos",
"requestId": "req_5f0c…",
"details": { "in": "body", "issues": [{ "path": "cpf", "message": "CPF inválido" }] }
}
}O code é estável (use-o na lógica do seu código); a message pode mudar. Informe o requestId (também no cabeçalho X-Request-Id) ao falar com o suporte.
Autenticação e requisição
| HTTP | Código | O que fazer |
|---|---|---|
| 401 | INVALID_CREDENTIALS |
revise a chave e os cabeçalhos (HMAC) |
| 401 | INVALID_SIGNATURE |
revise a string canônica, o corpo e o secret |
| 401 | TIMESTAMP_OUT_OF_RANGE |
sincronize o relógio (±5 min) |
| 403 | OPERATOR_SUSPENDED |
fale com a equipe |
| 403 | FORBIDDEN_IP |
o IP de saída não está na lista permitida |
| 403 | SANDBOX_ONLY |
rota exclusiva de sandbox chamada com chave de produção |
| 400 | IDEMPOTENCY_KEY_REQUIRED |
envie Idempotency-Key |
| 409 | IDEMPOTENCY_CONFLICT |
a chave já foi usada com outro pedido |
| 409 | IDEMPOTENCY_IN_PROGRESS |
aguarde e repita com a mesma chave |
| 422 | VALIDATION_ERROR |
corrija os campos apontados em details.issues |
| 413 | PAYLOAD_TOO_LARGE |
o corpo excede 256 KB |
| 404 | NOT_FOUND |
rota ou recurso inexistente |
| 405 | METHOD_NOT_ALLOWED |
método incorreto (veja o cabeçalho Allow) |
| 429 | RATE_LIMITED |
aguarde Retry-After segundos e use backoff |
| 500 | INTERNAL_ERROR |
repita com a mesma Idempotency-Key; persistindo, informe o requestId |
Domínio
| HTTP | Código | Significado |
|---|---|---|
| 404 | PLAYER_NOT_FOUND |
jogador inexistente ou de outra marca |
| 409 | PLAYER_ALREADY_EXISTS |
externalId, e-mail ou CPF já cadastrado (details.field) |
| 409 | PLAYER_NOT_ACTIVE |
conta suspensa, bloqueada, restrita ou encerrada |
| 403 | KYC_REQUIRED |
a operação exige KYC aprovado |
| 409 | KYC_ALREADY_APPROVED |
o KYC já foi aprovado |
| 409 | RG_BLOCKED |
bloqueio de jogo responsável (autoexclusão ou limite diário) |
| 422 | CURRENCY_MISMATCH |
a moeda difere da moeda do jogador |
| 402 | INSUFFICIENT_BALANCE |
saldo disponível para saque insuficiente (details.withdrawable) |
| 409 | BONUS_ROLLOVER_PENDING |
há bônus com rollover pendente |
| 404 / 409 | DEPOSIT_NOT_FOUND / DEPOSIT_NOT_PENDING / DEPOSIT_ALREADY_EXISTS |
depósito inexistente, já processado ou externalReference repetida |
| 404 / 409 | WITHDRAWAL_NOT_FOUND / WITHDRAWAL_NOT_CANCELLABLE |
saque inexistente ou já aprovado |
| 409 | INVALID_WITHDRAWAL_STATE |
(sandbox) a decisão não vale para o estado atual do saque |
| 404 | GAME_NOT_FOUND |
jogo inexistente ou desativado |
| 502 | PROVIDER_UNAVAILABLE |
o Game Provider não respondeu; tente novamente |
Como tratar
4xx: o pedido está incorreto ou viola uma regra; não repita igual.5xxe timeouts: repita com a mesmaIdempotency-Key, com backoff exponencial.429: respeite oRetry-After.