Erros e limites

O que cada código significa e quantos pedidos podes fazer.

Um erro devolve sempre o mesmo formato: um code estável, para o teu programa decidir, e uma message em português, para aparecer a uma pessoa. Trata o code, nunca o texto: a mensagem pode mudar, o código não.

json

{
  "error": {
    "code": "device_offline",
    "message": "O telemovel dev_oppo_cph2577 esta offline desde 14:02.",
    "requestId": "req_01H8X2K9"
  }
}

Estados HTTP

Estado	Significado	O que fazer
`200`	aceite	nada
`400`	o pedido está mal formado	corrigir o corpo; repetir não ajuda
`401`	chave inválida ou revogada	criar uma chave nova
`402`	sem mensagens no plano	esperar pela renovação ou mudar de plano
`404`	o dispositivo não existe	confirmar o deviceId em /devices
`409`	o dispositivo está offline	esperar ou enviar por outro
`429`	demasiados pedidos	esperar o que diz Retry-After
`5xx`	falha do nosso lado	repetir com espera crescente

Códigos de erro

Código	Quando acontece
`invalid_number`	o número não está em E.164 ou não existe
`message_too_long`	acima de 1530 caracteres
`device_offline`	o telemóvel escolhido não está ligado
`device_not_found`	o deviceId não pertence à conta
`quota_exceeded`	as mensagens do mês acabaram
`rate_limited`	acima de 60 pedidos por minuto
`invalid_key`	a chave foi revogada ou nunca existiu

Limites

Limite	Valor
`Pedidos à API`	60 por minuto e por chave
`Envio por telemóvel`	cerca de 40 mensagens por minuto
`Fila por telemóvel`	5000 mensagens
`Tamanho do corpo`	256 kB

O limite real é o do telemóvel, não o da API

A API aceita 60 pedidos por minuto, mas um telemóvel Android envia cerca de 40 mensagens por minuto. Aceitar depressa de mais só faz crescer a fila: para 10 000 mensagens conta com umas quatro horas num telemóvel, ou divide por vários.