Quais Códigos de Status HTTP APIs REST Devem Usar?

Em resumo

APIs REST devem usar códigos de status HTTP corretamente: 200 para GET bem-sucedido, 201 para POST bem-sucedido com criação de recurso, 204 para DELETE bem-sucedido, 400 para erros do cliente, 401 para falhas de autenticação, 404 para não encontrado e 500 para erros do servidor. A Modern PetstoreAPI implementa todos os códigos de status HTTP padrão com semânticas adequadas e respostas de erro RFC 9457.

Introdução

Sua API retorna 200 OK para tudo. Sucesso? 200 OK. Erro de validação? 200 OK com uma mensagem de erro no corpo. Recurso não encontrado? 200 OK com {"error": "not found"}. Falha de autenticação? Você adivinhou — 200 OK.

Isso está errado. Os códigos de status HTTP existem por um motivo. Eles informam aos clientes o que aconteceu sem analisar o corpo da resposta. Caches, proxies e ferramentas de monitoramento dependem dos códigos de status. Quando você retorna 200 para erros, você quebra todo o ecossistema HTTP.

A antiga Swagger Petstore cometeu erros de código de status: retornando 200 para requisições POST que deveriam retornar 201, usando 200 para operações DELETE que deveriam retornar 204, e perdendo códigos de erro importantes. A Modern PetstoreAPI corrige isso implementando semânticas HTTP adequadas em todos os endpoints.

💡

Se você está construindo ou testando APIs REST, o Apidog ajuda a validar o uso de códigos de status, testar cenários de erro e garantir que sua API siga os padrões HTTP. Você pode definir códigos de status esperados, executar testes automatizados e detectar respostas incorretas antes da implantação.

botão

Neste guia, você aprenderá quais códigos de status HTTP importam para APIs REST, quando usar cada um e como a Modern PetstoreAPI os implementa corretamente.

O Problema dos Códigos de Status

Muitas APIs tratam os códigos de status como algo secundário. O resultado: semânticas HTTP quebradas e clientes confusos.

O Anti-Padrão "200 OK para Tudo"

// Sucesso
GET /users/123
200 OK
{"id": 123, "name": "John"}

// Erro (mas ainda 200!)
GET /users/999
200 OK
{"error": "User not found"}

// Erro de validação (ainda 200!)
POST /users
200 OK
{"error": "Email is required"}

Problemas:

Os clientes não conseguem distinguir sucesso de falha sem analisar o corpo
Caches HTTP armazenam respostas de erro
Ferramentas de monitoramento relatam falsos positivos
A lógica de repetição não funciona corretamente

Por Que Isso Acontece

Os desenvolvedores retornam 200 porque:

Eles não conhecem os outros códigos de status
Eles acham que os códigos de status são opcionais
Eles querem evitar "quebrar" os clientes
Eles estão copiando maus exemplos (como a antiga Swagger Petstore)

Códigos de Status HTTP Essenciais para APIs REST

Você não precisa de todos os mais de 60 códigos de status HTTP. Concentre-se nestes essenciais.

Referência Rápida

Sucesso (2xx):

200 OK - GET, PUT, PATCH bem-sucedidos
201 Created - POST bem-sucedido com criação de recurso
204 No Content - DELETE, PUT bem-sucedidos sem corpo de resposta

Erros do Cliente (4xx):

400 Bad Request - Formato de requisição inválido ou erro de validação
401 Unauthorized - Autenticação ausente ou inválida
403 Forbidden - Autenticado, mas não autorizado
404 Not Found - Recurso não existe
409 Conflict - Conflito de recurso (duplicidade, incompatibilidade de versão)
422 Unprocessable Entity - Formato válido, mas erros semânticos
429 Too Many Requests - Limite de taxa excedido

Erros do Servidor (5xx):

500 Internal Server Error - Erro inesperado do servidor
502 Bad Gateway - Erro de serviço upstream
503 Service Unavailable - Indisponibilidade temporária
504 Gateway Timeout - Tempo limite do gateway

Códigos de Sucesso (2xx)

Os códigos de sucesso indicam que a requisição foi bem-sucedida. Diferentes códigos transmitem diferentes significados.

200 OK

Use para: Requisições GET, PUT, PATCH bem-sucedidas que retornam dados.

GET /pets/123
200 OK
{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "species": "CAT"
}

Não use para: Requisições POST que criam recursos (use 201), requisições DELETE (use 204).

201 Created

Use para: Requisições POST bem-sucedidas que criam um novo recurso.

POST /pets
201 Created
Location: https://petstoreapi.com/pets/019b4132-70aa-764f-b315-e2803d882a24
{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "species": "CAT"
}

Pontos-chave:

Inclua o cabeçalho Location com a URL do novo recurso
Retorne o recurso criado no corpo da resposta
Os clientes sabem que um recurso foi criado, não apenas atualizado

A Modern PetstoreAPI retorna 201 para todas as operações POST que criam recursos.

204 No Content

Use para: Requisições DELETE, PUT ou PATCH bem-sucedidas sem corpo de resposta.

DELETE /pets/019b4132-70aa-764f-b315-e2803d882a24
204 No Content

Pontos-chave:

Sem corpo de resposta (economiza largura de banda)
Indica sucesso
Comum para operações DELETE

Códigos de Erro do Cliente (4xx)

Os códigos de erro do cliente indicam que o cliente cometeu um erro. A requisição não deve ser repetida sem modificação.

400 Bad Request

Use para: Requisições malformadas, JSON inválido, campos obrigatórios ausentes.

POST /pets
400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "invalid-params": [
    {
      "name": "name",
      "reason": "Name is required"
    }
  ]
}

A Modern PetstoreAPI usa o formato RFC 9457 para todas as respostas de erro.

401 Unauthorized

Use para: Credenciais de autenticação ausentes ou inválidas.

GET /pets
401 Unauthorized
WWW-Authenticate: Bearer realm="PetstoreAPI"

{
  "type": "https://petstoreapi.com/errors/authentication-required",
  "title": "Authentication Required",
  "status": 401,
  "detail": "Valid authentication credentials required"
}

Pontos-chave:

Inclua o cabeçalho WWW-Authenticate
O cliente deve solicitar credenciais ou um token de atualização
Não confunda com 403 (autorização)

403 Forbidden

Use para: Usuário autenticado não possui permissão.

DELETE /pets/019b4132-70aa-764f-b315-e2803d882a24
403 Forbidden

{
  "type": "https://petstoreapi.com/errors/insufficient-permissions",
  "title": "Insufficient Permissions",
  "status": 403,
  "detail": "You don't have permission to delete this pet"
}

Diferença de 401:

401: "Quem é você?" (autenticação)
403: "Eu sei quem você é, mas você não pode fazer isso" (autorização)

404 Not Found

Use para: Recurso não existe.

GET /pets/nonexistent-id
404 Not Found

{
  "type": "https://petstoreapi.com/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Pet not found"
}

Não use para: Falhas de autorização (use 403), erros de validação (use 400).

409 Conflict

Use para: Conflitos de recursos como duplicidade ou incompatibilidade de versão.

POST /pets
409 Conflict

{
  "type": "https://petstoreapi.com/errors/duplicate-resource",
  "title": "Duplicate Resource",
  "status": 409,
  "detail": "A pet with this microchip ID already exists"
}

422 Unprocessable Entity

Use para: Formato de requisição válido, mas com erros semânticos.

POST /pets
422 Unprocessable Entity

{
  "type": "https://petstoreapi.com/errors/business-rule-violation",
  "title": "Business Rule Violation",
  "status": 422,
  "detail": "Cannot adopt more than 5 pets per household"
}

Diferença de 400:

400: Requisição malformada (JSON inválido, tipos incorretos)
422: Requisição bem-formada, mas viola regras de negócio

429 Too Many Requests

Use para: Limite de taxa excedido.

GET /pets
429 Too Many Requests
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 1678886400

{
  "type": "https://petstoreapi.com/errors/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "Rate limit of 100 requests per hour exceeded"
}

A Modern PetstoreAPI usa cabeçalhos de limite de taxa IETF.

Códigos de Erro do Servidor (5xx)

Os códigos de erro do servidor indicam que o servidor falhou. Os clientes podem tentar novamente essas requisições.

500 Internal Server Error

Use para: Erros inesperados do servidor.

GET /pets
500 Internal Server Error

{
  "type": "https://petstoreapi.com/errors/internal-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred"
}

Não inclua: Rastros de pilha (stack traces), detalhes internos, erros de banco de dados em produção.

503 Service Unavailable

Use para: Indisponibilidade temporária (manutenção, sobrecarga).

GET /pets
503 Service Unavailable
Retry-After: 3600

{
  "type": "https://petstoreapi.com/errors/service-unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Service temporarily unavailable for maintenance"
}

Inclua o cabeçalho Retry-After para informar aos clientes quando tentar novamente.

Como a Modern PetstoreAPI Usa Códigos de Status

A Modern PetstoreAPI implementa semânticas HTTP adequadas em todos os endpoints.

Exemplo: Gerenciamento de Animais de Estimação

// Listar animais de estimação
GET /pets
200 OK

// Criar animal de estimação
POST /pets
201 Created
Location: https://petstoreapi.com/pets/{id}

// Obter animal de estimação
GET /pets/{id}
200 OK (encontrado) ou 404 Not Found

// Atualizar animal de estimação
PUT /pets/{id}
200 OK (com corpo) ou 204 No Content

// Excluir animal de estimação
DELETE /pets/{id}
204 No Content (sucesso) ou 404 Not Found

Respostas de Erro

Todos os erros usam o formato RFC 9457:

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "instance": "/pets",
  "invalid-params": [
    {
      "name": "name",
      "reason": "Name must be between 1 and 100 characters"
    }
  ]
}

Consulte a documentação de tratamento de erros da Modern PetstoreAPI para exemplos completos.

Testando Códigos de Status com Apidog

O Apidog ajuda você a testar o comportamento dos códigos de status em todos os cenários.

Defina Códigos de Status Esperados

paths:
  /pets:
    post:
      responses:
        '201':
          description: Animal de estimação criado
        '400':
          description: Erro de validação
        '401':
          description: Autenticação necessária
        '429':
          description: Limite de taxa excedido

Teste Todos os Cenários

Crie casos de teste para:

Cenários de sucesso (200, 201, 204)
Erros de validação (400, 422)
Autenticação/autorização (401, 403)
Não encontrado (404)
Limitação de taxa (429)
Erros de servidor (500, 503)

Testes Automatizados

// Script de teste do Apidog
pm.test("Retorna 201 para criação bem-sucedida", () => {
  pm.response.to.have.status(201);
  pm.response.to.have.header("Location");
});

pm.test("Retorna 400 para campos obrigatórios ausentes", () => {
  pm.response.to.have.status(400);
  pm.expect(pm.response.json().type).to.include("validation-error");
});

Erros Comuns a Evitar

Erro 1: Usar 200 para POST

// Errado
POST /pets
200 OK

// Correto
POST /pets
201 Created
Location: https://petstoreapi.com/pets/{id}

Erro 2: Usar 200 para DELETE

// Errado
DELETE /pets/{id}
200 OK
{"message": "Deleted successfully"}

// Correto
DELETE /pets/{id}
204 No Content

Erro 3: Confundir 401 e 403

// Errado: Usuário está autenticado, mas não tem permissão
401 Unauthorized

// Correto
403 Forbidden

Erro 4: Usar 500 para Erros do Cliente

// Errado: Erro de validação retorna 500
POST /pets
500 Internal Server Error

// Correto
POST /pets
400 Bad Request

Conclusão

Os códigos de status HTTP não são opcionais. Eles fazem parte da especificação HTTP e são essenciais para construir APIs REST adequadas.

Use os códigos de status corretos:

200 para leituras bem-sucedidas
201 para criações bem-sucedidas
204 para exclusões bem-sucedidas
400 para erros do cliente
401 para autenticação
404 para não encontrado
500 para erros do servidor

A Modern PetstoreAPI demonstra o uso correto de códigos de status em todos os endpoints. Estude a documentação da API REST para ver a implementação adequada.

Teste seus códigos de status com o Apidog para garantir que sua API siga os padrões HTTP.

Perguntas Frequentes (FAQ)

Devo usar 200 ou 204 para um DELETE bem-sucedido?

Use 204 No Content. Ele indica sucesso sem um corpo de resposta, economizando largura de banda. Use 200 apenas se precisar retornar informações sobre o recurso excluído.

Qual a diferença entre 400 e 422?

400 significa que a requisição está malformada (JSON inválido, tipos incorretos). 422 significa que a requisição está bem-formada, mas viola regras de negócio.

Quando devo usar 401 vs 403?

401 significa "autentique-se" (credenciais ausentes ou inválidas). 403 significa "você está autenticado, mas não autorizado" (permissões insuficientes).

Devo retornar 404 ou 403 para recursos que os usuários não podem acessar?

Retorne 403 se o recurso existir, mas o usuário não tiver permissão. Retorne 404 se você quiser ocultar a existência do recurso de usuários não autorizados.

Como faço para testar todos os cenários de códigos de status?

Use o Apidog para criar casos de teste para sucesso, erros de validação, falhas de autenticação, não encontrado e erros de servidor. Execute testes automatizados em CI/CD.

Qual código de status para limitação de taxa?

Use 429 Too Many Requests com cabeçalhos RateLimit-*. Inclua Retry-After para informar aos clientes quando podem tentar novamente.

Devo usar 500 para todos os erros de servidor?

Use 500 para erros inesperados. Use 502 para falhas de serviço upstream, 503 para indisponibilidade temporária e 504 para tempos limite.

Como a Modern PetstoreAPI lida com erros?

Todos os erros usam o formato RFC 9457 com códigos de status apropriados. Consulte a documentação de tratamento de erros para exemplos.