Erros

Toda falha, em toda rota, usa um envelope só:

{ "error": { "code": "invalid_request", "message": "seats_total must be 2..8" } }

Ramifique pelo code. Ele é estável, enquanto message é escrito para humanos e pode ser reescrito sem aviso.

O envelope cobre a superfície inteira, incluindo respostas que um framework normalmente produziria sozinho: 404 em caminho desconhecido e 405 em verbo errado voltam nesse formato.

A única exceção é o handshake do WebSocket, servido por outro processo e que responde texto puro.

O catálogo

Código	Status	Significado	O que fazer
unauthorized	401	Chave ausente, malformada, desconhecida, revogada ou expirada	Corrija a credencial. Não retente
forbidden	403	Falta escopo, tenant suspenso, não é o criador, ou tenant divergente	Leia message. Não retente
game_not_allowed	403	O jogo não está na allowlist deste casino	Mande liberar, espere ~30 s e retente
not_found	404	Batalha inexistente para este casino, jogo desconhecido, ou caminho desconhecido	Não retente
invalid_request	400	Validação falhou, JSON malformado, campo desconhecido, ou conteúdo sobrando	Corrija a requisição
conflict	409	Conflito de estado: já sentado, sem assento vazio, batalha fora de OPEN	Releia o estado; não retente às cegas
request_too_large	413	Corpo acima de 1 MiB	Corrija a requisição
unavailable	503	Ainda subindo, ou em capacidade máxima	Retente com backoff
internal	500 / 502	Falha do servidor, ou falha de provedor upstream	Retente uma vez, depois alerte
method_not_allowed	405	Verbo errado num caminho que existe	Corrija a requisição

Só unavailable é rotineiramente retentável

503 unavailable significa que a instância está subindo, ou está no limite de batalhas em voo. Backoff exponencial com jitter é a resposta certa, e a requisição provavelmente vai passar.

500/502 internal vale uma retentativa. Um 502 em bot-seats especificamente significa que um provedor upstream falhou ao emitir uma sessão, o que costuma ser transitório.

Todo o resto é determinístico. Retentar um 400 produz outro 400.

Os que enganam

403 game_not_allowed logo depois de o jogo ser liberado. O catálogo é cacheado, e uma mudança pode levar até 30 segundos para chegar na API. Mudança feita no console é imediata; a que o seu host faz para você pode não ser. Espere meio minuto e retente antes de tratar como erro. Verificado ao vivo.

404 numa batalha que você tem certeza que existe. Ou ela é de outro casino, ou a sua chave é. Leituras cross-tenant respondem 404 em vez de 403, o que torna isso indistinguível de um erro de digitação. Confira qual chave você mandou antes de caçar a batalha.

400 unknown field "tenant_id". O tenant vem da chave. Remova o campo.

409 player is already in an active battle. Um jogador, uma batalha ativa, por casino. A batalha anterior dele não chegou a um estado terminal, e ela pode estar esperando a janela do lobby em vez de estar realmente rodando.

500 failed to mint viewer token. Não é bug na sua chamada. A instância não tem chave de assinatura de viewer, então a visualização ao vivo fica indisponível enquanto as batalhas funcionam normalmente. Veja Tokens de viewer.

Um 405 inesperado. Todo caminho responde todo verbo com um 405 explícito mais um header Allow nomeando o que ele aceita. Leia o header:

HTTP/1.1 405 Method Not Allowed
Allow: GET

Mensagens de validação

Falhas de validação retornam a mesma mensagem que o próprio serviço teria produzido, então elas são específicas e seguras de logar:

Mensagem	Causa
seats_total must be 2..8	Capacidade fora do intervalo
player_ref is required	player_ref / creator_player_ref faltando
game_url is required for human players	game_url faltando num assento
unknown game_id	game_id faltando ou desconhecido
battle not found	Id desconhecido, ou de outro casino
player is already in an active battle	A regra de uma batalha por jogador
game not allowed for tenant	Allowlist
tenant suspended	O casino está suspenso
tenant mismatch	O tenant_id do corpo diverge da chave

Só o erro de um campo é retornado por requisição, numa precedência fixa, então corrija um de cada vez em vez de esperar uma lista completa.

Logging

Logue code, o status HTTP e o id da batalha. Logue message também, mas nunca use como chave.

Nunca logue o corpo de uma criação de batalha ou de uma chamada de assento: ele contém game_url / creator_game_url, que são URLs de sessão de provedor ao vivo. O SlotBattle nunca as deixa cruzar uma fronteira de processo, e os seus logs devem manter a mesma linha.

Próximo

• Autenticação: os casos de 401/403 em detalhe
• Referência completa com Try It