Folha de dicas de API RESTful

REST (Representational State Transfer) é um estilo arquitetural para projetar serviços de API web em rede sobre HTTP.

Verbos HTTP e semântica

---

Códigos de status HTTP comuns

Sucesso (2xx)

• 200 OK: Solicitação bem-sucedida (corpo contém a representação).
• 201 Created: Recurso criado com sucesso (cabeçalho Location indica a URI).
• 202 Accepted: Solicitação aceita para processamento assíncrono.
• 204 No Content: Ação bem-sucedida, sem corpo de resposta (comum no DELETE).

Erros de cliente (4xx)

• 400 Bad Request: Sintaxe malformada, parâmetros inválidos ou falha de validação.
• 401 Unauthorized: Autenticação ausente ou inválida.
• 403 Forbidden: Usuário autenticado não tem permissão para acessar o recurso.
• 404 Not Found: A URI do recurso não existe.
• 409 Conflict: Solicitação conflita com o estado atual do recurso (ex.: chave única duplicada).
• 422 Unprocessable Entity: Solicitação bem formada falhou na validação semântica de domínio.
• 429 Too Many Requests: Limite de taxa (Rate Limit) excedido.

Erros de servidor (5xx)

• 500 Internal Server Error: Falha genérica não tratada no servidor.
• 502 Bad Gateway: O servidor upstream retornou uma resposta inválida.
• 503 Service Unavailable: Servidor sobrecarregado ou em manutenção.

---

Envelope de erro JSON padrão

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The email address provided is already registered.",
    "details": [
      {
        "field": "email",
        "issue": "unique_constraint_violated"
      }
    ]
  }
}

---

Referências

• Folha de dicas de códigos de status HTTP
• RFC 9110: Semântica HTTP