Error Codes
Referência de erros HTTP da API FourPlay e respostas esperadas nos callbacks de wallet
Formato de Erro
A API FourPlay retorna erros em formato JSON simples:
Mines Provider (mines.fourplay.studio):
{
"message": "Descrição do erro"
}Portal Admin (admin.fourplay.studio):
{
"error": "Descrição do erro"
}Não existe campo code, request_id ou timestamp no formato de erro. Use o campo message (ou error) para diagnóstico e logging.
Status HTTP da Session API
| HTTP | Quando ocorre | Corpo |
|---|---|---|
| 200 | Sucesso | Body específico do endpoint |
| 400 | Campo obrigatório ausente ou body inválido | { "message": "Missing required fields" } |
| 401 | HMAC inválido, timestamp fora da janela, operador não encontrado | { "message": "Invalid signature" } ou { "message": "Operator not found" } |
| 403 | Operador inativo ou suspenso | { "message": "Operator is inactive" } |
| 500 | Erro interno do Mines Provider | { "message": "Internal server error" } |
Erros de Autenticação HMAC
| Situação | HTTP | Mensagem provável |
|---|---|---|
| API Key não reconhecida | 401 | "Operator not found" |
| Assinatura HMAC incorreta | 401 | "Invalid signature" |
| Timestamp fora da janela de ±5 minutos | 401 | "Request expired" ou similar |
Headers X-Operator-Id/X-Timestamp/X-Signature ausentes | 400 | "Missing required fields" |
| Operador com status inativo | 403 | "Operator is inactive" |
Como diagnosticar Invalid signature:
- Confirme que o timestamp está em milissegundos (13 dígitos), não em segundos
- Confirme que a data do HMAC é exatamente:
apiKey + timestamp + bodyJson - Confirme que o body enviado é idêntico ao usado para calcular a assinatura (mesma serialização JSON)
- Verifique o NTP do servidor (drift de relógio causa rejeição por timestamp)
Erros da Session API
| Endpoint | Situação | HTTP | Mensagem |
|---|---|---|---|
/session/create | externalPlayerId ausente | 400 | "Missing required fields" |
/session/create | Operador não encontrado | 401 | "Operator not found" |
/session/create | Assinatura inválida | 401 | "Invalid signature" |
/session/create | Operador inativo | 403 | "Operator is inactive" |
/session/validate | Token ausente | 400 | "Token is required" |
/session/validate | Token inválido ou expirado | 401 | "Invalid token" |
Respostas dos Callbacks de Wallet
Estes são os status HTTP que seu servidor deve retornar para o FourPlay:
/wallet/balance
| Situação | HTTP | Body que você deve retornar |
|---|---|---|
| Sucesso | 200 | { "balance": 50000 } |
| Assinatura inválida | 401 | { "error": "Invalid signature" } |
| Jogador não encontrado | 404 | { "message": "Player not found" } |
| Erro interno no seu servidor | 500 | Qualquer mensagem de erro |
/wallet/debit
| Situação | HTTP | Body que você deve retornar |
|---|---|---|
| Sucesso | 200 | { "balance": 49000, "transactionId": "tx_..." } |
gameId já processado (idempotência) | 200 | { "balance": <atual>, "transactionId": "<id original>" } |
| Saldo insuficiente | 422 | { "message": "Insufficient balance" } |
| Jogador não encontrado | 404 | { "message": "Player not found" } |
| Assinatura inválida | 401 | { "error": "Invalid signature" } |
/wallet/credit
| Situação | HTTP | Body que você deve retornar |
|---|---|---|
| Sucesso | 200 | { "balance": 52500, "transactionId": "tx_..." } |
gameId já processado (idempotência) | 200 | { "balance": <atual>, "transactionId": "<id original>" } |
| Jogador não encontrado | 404 | { "message": "Player not found" } |
| Assinatura inválida | 401 | { "error": "Invalid signature" } |
/wallet/rollback
| Situação | HTTP | Body que você deve retornar |
|---|---|---|
| Sucesso (ou já revertido — idempotência) | 200 | {} |
| Debit original não encontrado | 404 | { "message": "Transaction not found" } |
| Assinatura inválida | 401 | { "error": "Invalid signature" } |
Rollback não lê o body de resposta
O FourPlay Mines não lê o body da resposta do rollback — apenas verifica HTTP 200. Você pode retornar {} ou qualquer JSON válido.
Comportamento do FourPlay em Caso de Erro nos Callbacks
| Sua resposta | O que o FourPlay faz |
|---|---|
| 200 | Operação confirmada — prossegue |
| 401 | Loga erro de autenticação — não tenta novamente |
| 404 | Erro permanente — não tenta novamente |
| 422 | Saldo insuficiente ou erro semântico — sem retry, cancela |
| 500 | Erro temporário — pode tentar novamente |
| Timeout (> 5s) | Tratado como falha — pode acionar rollback automático |
Idempotência é fundamental
O FourPlay pode chamar o mesmo callback mais de uma vez em caso de falha de rede ou retry. Implemente idempotência usando gameId + type como chave para evitar processamento duplicado.
Guia de Diagnóstico Rápido
| Sintoma | Causa provável | Solução |
|---|---|---|
401 Invalid signature | HMAC incorreto | Verificar fórmula: apiKey + timestamp_ms + body |
401 Request expired | Timestamp desatualizado | Usar milissegundos (Date.now()), checar NTP |
401 Operator not found | API Key errada ou inativa | Verificar X-Operator-Id no Portal Admin |
403 Operator is inactive | Conta suspensa | Contatar suporte@fourplay.studio |
| Callback com assinatura inválida recebido | Secretkey/body diferente | Logar raw body e recalcular HMAC para comparar |
| Jogo não abre | Token inválido ou expirado | Criar nova sessão (token expira em 24h) |
| Debit debitado duas vezes | Falta de idempotência | Implementar verificação por gameId + type |