Erros e limites

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

Os erros têm sempre o mesmo formato. Programa contra o code, nunca contra a message: o texto pode mudar, o código não.

json

{
  "error": {
    "code": "device_not_found",
    "message": "Device dev_oppo_cph2577 not found.",
    "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
`429`	demasiados pedidos	abrandar; o limite renova a cada minuto
`5xx`	falha do nosso lado	repetir com a mesma Idempotency-Key

Códigos de erro

Código	Quando acontece
`validation_error`	falta um campo ou está mal formado
`invalid_number`	o número não está em E.164 ou não existe
`message_too_long`	acima de 10 segmentos (1530 caracteres GSM-7, 670 Unicode)
`device_not_found`	o deviceId não pertence à conta
`quota_exceeded`	as mensagens deste ciclo acabaram
`rate_limited`	acima do limite de pedidos desta conta
`invalid_key`	a chave foi revogada ou nunca existiu

Limites

Limite	Valor
`Pedidos à API`	60 por minuto e por chave, multiplicado pelos telemóveis ligados à conta (até 3000)
`Envio por telemóvel`	cerca de 30 mensagens por minuto, ditado pelo telemóvel e pela operadora
`Mensagens por ciclo`	a quota do teu plano; cada resposta diz quanto falta
`Comprimento da mensagem`	10 segmentos
`Campo reference`	200 caracteres

Um telemóvel offline não recusa a mensagem

Entra na fila e sai quando o telemóvel voltar. A resposta traz `deviceOnline: false`, para distinguires "sai num segundo" de "está à espera de um telemóvel". Sem deviceId, é usado o telemóvel com a fila mais curta.

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

Um telemóvel envia cerca de 30 mensagens por minuto. O que for aceite acima disso fica na fila.