Erros da API

A API reporta erros com códigos de status HTTP padrão e um corpo de resposta unificado. Respostas bem-sucedidas retornam dados diretamente, sem envelope.

Formato do erro

Em caso de erro, o corpo da resposta é um objeto JSON com um campo error contendo uma mensagem legível por humanos:

{"error":"reaction not found"}

Oriente-se pelo código de status HTTP em primeiro lugar, e use o texto de error para logs e dicas ao usuário.

Códigos de status

  • 200 OK — requisição bem-sucedida, dados no corpo.
  • 201 Created — novo recurso criado (alguns endpoints POST).
  • 204 No Content — sucesso sem corpo (algumas exclusões).
  • 400 Bad Request — corpo ou parâmetros de requisição incorretos.
  • 401 Unauthorized — token ausente, inválido ou expirado; ou rota não acessível via token pessoal.
  • 402 Payment Required — ação limitada por plano ou cota (por exemplo, armazenamento de mídia próprio requer premium).
  • 403 Forbidden — o token não possui o escopo necessário para esta rota.
  • 404 Not Found — recurso não encontrado ou não pertence a você.
  • 409 Conflict — conflito de estado (por exemplo, duplicação de valor único).
  • 422 Unprocessable Entity — o corpo é sintaticamente válido, mas não passa nas validações do domínio.
  • 429 Too Many Requests — limite de requisições excedido (veja limites).
  • 500 Internal Server Error — erro interno do servidor; tente novamente mais tarde.

Como tratar

Considere sucesso os códigos 2xx. Para 401/403, verifique o token e seus escopos. Para 4xx (exceto 429), não repita a requisição sem alterações — corrija a requisição. Para 429 e 5xx, é apropriado tentar novamente com backoff exponencial.

Próximos passos