MostlyQR

Erros

A API REST usa códigos de status HTTP padrão e retorna um corpo de erro JSON:

json
{ "error": "unauthorized", "message": "Missing or invalid API key" }

# Status codes

Status error Quando
400 invalid-argument Corpo malformado ou campo obrigatório ausente.
401 unauthorized Chave de API ausente, inválida ou revogada.
403 permission-denied Além do direito do seu plano (um recurso que seu plano não inclui).
404 not-found Nenhum link/campanha/job com esse id, ou não pertence à sua conta.
405 method_not_allowed Esse método HTTP não é suportado no caminho.
409 failed-precondition O recurso não está em um estado que permite a operação — por exemplo, editar um link congelado ou emitir códigos serializados além da sua alocação Enterprise (o limite está na mensagem).
429 rate_limited / resource-exhausted Limite de taxa por chave atingido (rate_limited — inclui um timestamp retry_at e headers de resposta X-RateLimit-*) ou cota do plano esgotada (resource-exhausted). Aguarde e tente novamente.
5xx internal Algo deu errado da nossa parte; seguro para tentar novamente leituras idempotentes.

Erros no nível de transporte (autenticação, roteamento, rate-limiting) usam códigos em snake_case; erros no nível de recurso usam kebab-case (a convenção Firebase callable). Sempre ramifique no status HTTP, não na string error.

# Propriedade

Cada leitura e escrita tem escopo para a conta que a chave de API resolve. Solicitar um link ou campanha de outra conta retorna 404 (não 403) — não revelamos que ela existe.

# Jobs assíncronos

Jobs de batch e serialized mint aceitam a solicitação (200, queued), então exibem falhas no status do job (status: "failed" com um motivo), não na resposta HTTP original. Sempre faça polling do job.

# Verificação

Os endpoints públicos de verificação nunca erram em um serial desconhecido — retornam status: "unknown" (um código falso/não emitido é uma resposta significativa, não um 404).

# Próximo