O cabeçalho Location é obrigatório no 201?

Não estritamente. A RFC 9110 diz que o recurso novo é identificado pelo Location ou, na falta dele, pela URL do pedido. Num POST para uma coleção a URL nova é diferente da URL do pedido, então na prática envie sempre.

A resposta 201 deve ter corpo?

Pode e normalmente deve. A especificação diz que o conteúdo costuma descrever e apontar para os recursos criados; a maioria das APIs devolve o objeto completo para o cliente receber na hora os campos gerados no servidor.

Qual status um PUT deve devolver quando cria o recurso?

201 Created. A RFC 9110, seção 9.3.4, exige 201 quando o PUT cria uma representação que não existia, e 200 ou 204 quando substitui uma que já existia.

Como evitar registros duplicados quando o cliente repete um POST?

Peça ao cliente um cabeçalho Idempotency-Key único e guarde-o junto com o resultado. Quando a mesma chave chegar de novo, devolva o 201 guardado em vez de criar outro registro.

Código de status HTTP · Sucesso (2xx)

201 Created

O 201 Created significa que o pedido deu certo e criou um ou mais recursos novos, normalmente depois de um POST numa coleção ou de um PUT numa URL nova. A resposta deve trazer um cabeçalho Location com a URL do recurso criado; sem ele, a própria URL do pedido é considerada o recurso criado.

Dados sobre este código de status
Classe	2xx, Sucesso
Definido em	RFC 9110 §15.3.2
Pode ir para o cache por padrão	Só com Cache-Control ou Expires explícitos
Pode repetir o pedido	Não repita um POST que recebeu 201, ou você cria uma duplicata
Cabeçalhos relevantes	`Location`: URL do novo recurso; sem ele, a própria URL do pedido é tomada como o recurso novo `ETag`: validador da representação recém-criada, útil para atualizações condicionais depois

O que significa o 201

A RFC 9110, seção 15.3.2, identifica o principal recurso novo pelo cabeçalho Location ou, quando ele não vem, pela URI do pedido. O corpo normalmente descreve o que foi criado e traz links para ele, e um ETag enviado junto é o validador da nova representação.

No PUT a regra é rígida: a seção 9.3.4 diz que, se o PUT criou uma representação que não existia, o servidor TEM de responder 201; se substituiu uma existente, responde 200 ou 204. Se o recurso só vai existir depois de um processamento em segundo plano, o 201 é precipitado e o 202 Accepted é a resposta honesta.

Quando usar

POST /pedidos que cria um pedido com ID escolhido pelo servidor: 201 mais Location: /pedidos/1234.
PUT /arquivos/relatorio.pdf que envia um arquivo que ainda não existia.
Devolva também o objeto criado no corpo, para o cliente não precisar de outro GET só para saber campos gerados no servidor, como id ou createdAt.

Causas comuns

Se você administra o servidor

Um POST repetido (clique duplo, timeout na rede móvel) volta 201 duas vezes e cria dois pedidos, porque POST não é idempotente.
O cliente não encontra o que criou: falta o Location, ou ele é relativo e o cliente o resolve contra a URL base errada.

Como resolver

Se você administra o servidor

Aceite um cabeçalho Idempotency-Key nos endpoints de criação e devolva o 201 original quando a mesma chave voltar.
Sempre envie o Location; um valor relativo como /pedidos/1234 é válido e é resolvido a partir da URL do pedido.

Como enviar um 201

Express (Node.js)

app.post('/reports', (req, res) => {
  res.set('Location', '/reports/42');
  res.status(201).json({ id: '42', title: 'Q3 revenue' });
});

Next.js App Router (route handler)

// app/reports/route.ts
export async function POST() {
  return Response.json(
    { id: '42', title: 'Q3 revenue' },
    { status: 201, headers: { 'Location': '/reports/42' } }
  );
}

Go net/http

mux.HandleFunc("POST /reports", func(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Location", "/reports/42")
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusCreated) // 201
	w.Write([]byte(`{"id":"42","title":"Q3 revenue"}`))
})

Python FastAPI

from fastapi import FastAPI
from fastapi.responses import JSONResponse

app = FastAPI()

@app.post("/reports")
def create_report():
    return JSONResponse(status_code=201, content={"id": "42", "title": "Q3 revenue"}, headers={"Location": "/reports/42"})

Costuma ser confundido com

201 vs 200: O 200 num POST informa que a ação deu certo; o 201 diz especificamente que algo novo passou a existir numa URL.
201 vs 202: O 202 Accepted indica que a criação foi enfileirada e ainda pode falhar; o 201 indica que o recurso já existe quando a resposta sai.
201 vs 303: Formulários HTML costumam responder a um POST bem-sucedido com 303 See Other para uma página de resultado (post/redirect/get); APIs respondem 201.

Perguntas frequentes

O cabeçalho Location é obrigatório no 201?: Não estritamente. A RFC 9110 diz que o recurso novo é identificado pelo Location ou, na falta dele, pela URL do pedido. Num POST para uma coleção a URL nova é diferente da URL do pedido, então na prática envie sempre.
A resposta 201 deve ter corpo?: Pode e normalmente deve. A especificação diz que o conteúdo costuma descrever e apontar para os recursos criados; a maioria das APIs devolve o objeto completo para o cliente receber na hora os campos gerados no servidor.
Qual status um PUT deve devolver quando cria o recurso?: 201 Created. A RFC 9110, seção 9.3.4, exige 201 quando o PUT cria uma representação que não existia, e 200 ou 204 quando substitui uma que já existia.
Como evitar registros duplicados quando o cliente repete um POST?: Peça ao cliente um cabeçalho Idempotency-Key único e guarde-o junto com o resultado. Quando a mesma chave chegar de novo, devolva o 201 guardado em vez de criar outro registro.

Revisado em 27 de setembro de 2026 por Arielton Oberek.