TL;DR
O RFC 9457 (Problem Details for HTTP APIs) é o formato padrão para respostas de erro de API. Ele substitui formatos de erro personalizados por uma estrutura consistente: `type`, `title`, `status`, `detail` e `instance`. O Modern PetstoreAPI implementa o RFC 9457 em todas as respostas de erro com negociação de conteúdo e detalhes de validação adequados.
Introdução
Sua API retorna um erro. Como é a resposta? Se você é como a maioria das APIs, inventou seu próprio formato:
{"error": "Invalid email"}
{"message": "Not found", "code": 404}
{"success": false, "errors": ["Email required"]}
Cada API tem um formato de erro diferente. Os clientes precisam de tratamento de erro personalizado para cada API. Não há uma maneira padrão de analisar erros, exibi-los aos usuários ou registrá-los para depuração.
O RFC 9457 resolve isso. É um padrão IETF que define como as APIs devem retornar erros. Em vez de inventar seu próprio formato, você usa um padrão comprovado que os clientes já entendem.
O antigo Swagger Petstore usava formatos de erro personalizados sem consistência. O Modern PetstoreAPI implementa o RFC 9457 em todas as respostas de erro, fornecendo detalhes de erro estruturados e legíveis por máquina.
Neste guia, você aprenderá o que é o RFC 9457, como implementá-lo corretamente e como o Modern PetstoreAPI o utiliza para todas as respostas de erro.
O Problema dos Erros de API
Antes do RFC 9457, cada API inventava seu próprio formato de erro.
Variações Comuns de Formatos de Erro
Formato 1: Mensagem simples
{"error": "User not found"}
Formato 2: Código e mensagem
{"code": "USER_NOT_FOUND", "message": "User not found"}
Formato 3: Estrutura aninhada
{
"success": false,
"error": {
"type": "NotFound",
"message": "User not found"
}
}
Formato 4: Array de erros
{
"errors": [
{"field": "email", "message": "Invalid email"}
]
}
Problemas com Formatos Personalizados
1. Sem consistência: Os clientes precisam de análise personalizada para cada API.
2. Falta de informações: Alguns formatos não possuem códigos de erro, outros não possuem detalhes, outros não possuem ambos.
3. Sem estrutura legível por máquina: Difícil de manipular erros programaticamente.
4. Fraca internacionalização: Mensagens de erro codificadas em inglês.
5. Sem padrão para erros de validação: Cada API lida com erros em nível de campo de forma diferente.
O Que é o RFC 9457?
O RFC 9457 (publicado em julho de 2023) define "Detalhes do Problema para APIs HTTP". É um padrão IETF que especifica como as APIs devem estruturar as respostas de erro.
Principais Características
Tipo de mídia padrão: application/problem+json (ou application/problem+xml)
Estrutura consistente: Todos os erros seguem o mesmo formato
Legível por máquina: Os clientes podem analisar erros programaticamente
Extensível: Você pode adicionar campos personalizados mantendo a compatibilidade
Consciente do HTTP: Integra-se com códigos de status HTTP
RFC 9457 vs. Erros Personalizados
Erro personalizado:
{"error": "Email is required"}
Erro RFC 9457:
{
"type": "https://petstoreapi.com/errors/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "The request contains invalid data",
"instance": "/pets",
"errors": [
{
"field": "email",
"message": "Email is required"
}
]
}
A versão do RFC 9457 fornece:
- URL do tipo de erro para documentação
- Título legível por humanos
- Código de status HTTP
- Explicação detalhada
- Caminho da solicitação que causou o erro
- Detalhes de validação em nível de campo
Estrutura do RFC 9457 Explicada
O RFC 9457 define cinco campos padrão e permite extensões personalizadas.
Campos Padrão
1. type (string, obrigatório)
Uma referência URI que identifica o tipo de erro. Deve apontar para documentação legível por humanos.
"type": "https://petstoreapi.com/errors/validation-error"
Se omitido, o padrão é about:blank.
2. title (string, obrigatório)
Um resumo curto e legível por humanos do tipo de erro. Não deve mudar entre ocorrências.
"title": "Validation Error"
3. status (number, obrigatório)
O código de status HTTP. Incluído para conveniência, para que os clientes não precisem analisar cabeçalhos.
"status": 400
4. detail (string, opcional)
Uma explicação legível por humanos específica para esta ocorrência do erro.
"detail": "The email field must be a valid email address"
5. instance (string, opcional)
Uma referência URI que identifica a ocorrência específica do erro. Geralmente, o caminho da solicitação.
"instance": "/pets/019b4132-70aa-764f-b315-e2803d882a24"
Extensões Personalizadas
Você pode adicionar campos personalizados para contexto adicional:
{
"type": "https://petstoreapi.com/errors/rate-limit-exceeded",
"title": "Rate Limit Exceeded",
"status": 429,
"detail": "You have exceeded the rate limit of 100 requests per minute",
"instance": "/pets",
"retryAfter": 42,
"limit": 100,
"remaining": 0,
"resetAt": "2026-03-13T10:30:00Z"
}
Como o Modern PetstoreAPI Implementa o RFC 9457
O Modern PetstoreAPI usa o RFC 9457 para todas as respostas de erro.
Exemplo 1: Recurso Não Encontrado
GET /pets/invalid-id
404 Not Found
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/not-found",
"title": "Resource Not Found",
"status": 404,
"detail": "The requested pet does not exist",
"instance": "/pets/invalid-id"
}
Exemplo 2: Erro de Autenticação
GET /pets
401 Unauthorized
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/unauthorized",
"title": "Authentication Required",
"status": 401,
"detail": "Valid authentication credentials are required to access this resource",
"instance": "/pets"
}
Exemplo 3: Limite de Taxa Excedido
GET /pets
429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 60
{
"type": "https://docs.petstoreapi.com/errors/rate-limit-exceeded",
"title": "Rate Limit Exceeded",
"status": 429,
"detail": "You have exceeded the rate limit of 100 requests per minute",
"instance": "/pets",
"limit": 100,
"remaining": 0,
"resetAt": "2026-03-13T10:31:00Z"
}
Veja a documentação de tratamento de erros do Modern PetstoreAPI para todos os tipos de erro.
Erros de Validação com RFC 9457
Erros de validação precisam de detalhes em nível de campo. O RFC 9457 permite extensões personalizadas para isso.
Formato de Validação do Modern PetstoreAPI
POST /pets
400 Bad Request
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "The request contains 2 validation errors",
"instance": "/pets",
"errors": [
{
"field": "name",
"message": "Name is required",
"code": "REQUIRED_FIELD"
},
{
"field": "species",
"message": "Species must be one of: DOG, CAT, BIRD, FISH, REPTILE, OTHER",
"code": "INVALID_ENUM_VALUE",
"rejectedValue": "DRAGON"
}
]
}
Pontos Chave
`errors` array: Contém detalhes de validação em nível de campo
`field`: O caminho JSON para o campo inválido
`message`: Mensagem de erro legível por humanos
`code`: Código de erro legível por máquina
`rejectedValue`: O valor que foi rejeitado (opcional)
Este formato permite que os clientes:
- Exibam erros em nível de campo em formulários
- Destaquem campos inválidos
- Forneçam mensagens de erro específicas
- Tratem erros programaticamente
Testando Respostas de Erro com Apidog
Apidog ajuda você a testar a conformidade com o RFC 9457.
Caso de Teste: Erro de Validação
// Apidog test script
pm.test("Returns RFC 9457 error format", () => {
const response = pm.response.json();
// Check required fields
pm.expect(response).to.have.property("type");
pm.expect(response).to.have.property("title");
pm.expect(response).to.have.property("status");
// Check status matches HTTP status
pm.expect(response.status).to.equal(pm.response.code);
// Check content type
pm.expect(pm.response.headers.get("Content-Type"))
.to.include("application/problem+json");
});
pm.test("Validation errors include field details", () => {
const response = pm.response.json();
pm.expect(response).to.have.property("errors");
pm.expect(response.errors).to.be.an("array");
response.errors.forEach(error => {
pm.expect(error).to.have.property("field");
pm.expect(error).to.have.property("message");
});
});
Caso de Teste: URLs de Tipo de Erro
pm.test("Error type URL is accessible", async () => {
const response = pm.response.json();
const typeUrl = response.type;
// Verify type URL returns documentation
const docResponse = await pm.sendRequest(typeUrl);
pm.expect(docResponse.code).to.equal(200);
});
Migração de Formatos de Erro Personalizados
Se você está usando formatos de erro personalizados, veja como migrar para o RFC 9457.
Passo 1: Adicionar o Cabeçalho Content-Type
Comece a retornar application/problem+json:
Content-Type: application/problem+json
Passo 2: Mapear Campos Existentes
Mapeie seu formato personalizado para o RFC 9457:
Antes:
{
"error": "USER_NOT_FOUND",
"message": "User not found"
}
Depois:
{
"type": "https://api.example.com/errors/user-not-found",
"title": "User Not Found",
"status": 404,
"detail": "User not found"
}
Passo 3: Suportar Ambos os Formatos (Período de Transição)
Use a negociação de conteúdo para suportar ambos os formatos:
Accept: application/json → Retorna formato personalizado
Accept: application/problem+json → Retorna formato RFC 9457
Passo 4: Depreciar Formato Personalizado
Após a migração dos clientes, deprecie o formato personalizado e retorne o RFC 9457 por padrão.
Conclusão
O RFC 9457 fornece um formato padrão para respostas de erro de API. Ele substitui formatos de erro personalizados por uma estrutura consistente e legível por máquina que os clientes podem analisar programaticamente.
O Modern PetstoreAPI implementa o RFC 9457 em todas as respostas de erro, demonstrando como estruturar erros corretamente com detalhes de validação adequados, URLs de tipo de erro e códigos de status HTTP.
Use o Apidog para testar a conformidade com o RFC 9457, validar estruturas de erro e garantir que sua API retorne respostas de erro adequadas.
FAQ
O RFC 9457 é obrigatório para APIs REST?
Não, mas é o padrão recomendado. Usar o RFC 9457 torna sua API mais consistente e fácil de integrar para os clientes.
Posso usar o RFC 9457 com XML?
Sim, o RFC 9457 define formatos tanto JSON (application/problem+json) quanto XML (application/problem+xml).
Devo sempre incluir todos os cinco campos padrão?
type, title e status são obrigatórios. detail e instance são opcionais, mas recomendados para um melhor contexto de erro.
Posso adicionar campos personalizados às respostas do RFC 9457?
Sim, o RFC 9457 é extensível. Você pode adicionar campos personalizados como errors, retryAfter ou traceId para contexto adicional.
Como lido com erros de validação com o RFC 9457?
Adicione um array errors personalizado com detalhes em nível de campo. O Modern PetstoreAPI mostra esse padrão em suas respostas de erro de validação.
Para onde a URL do tipo de erro deve apontar?
Deve apontar para uma documentação legível por humanos que explique o tipo de erro, as possíveis causas e como corrigi-lo.
Preciso alterar os códigos de status HTTP ao usar o RFC 9457?
Não, o RFC 9457 funciona com códigos de status HTTP padrão. O campo status na resposta deve corresponder ao código de status HTTP.
Como testo a conformidade com o RFC 9457?
Use o Apidog para validar a estrutura da resposta de erro, verificar os campos obrigatórios e verificar se os tipos de conteúdo correspondem às especificações do RFC 9457.