Erros

Todas as respostas de erro da API /api/v1 seguem o padrão RFC 7807 Problem Details (application/problem+json). Nunca analise o campo detail programaticamente: use type e status para roteamento de erros.

Formato

{
  "type": "urn:vestiai:error:validation",
  "title": "Validation Error",
  "status": 400,
  "detail": "O campo modelId é obrigatório.",
  "instance": "/api/v1/generations",
  "errors": [
    { "field": "modelId", "message": "Required" }
  ],
  "requestId": "req_abc123"
}

Campo	Sempre presente	Descrição
`type`	Sim	URI estável do tipo de erro. Use para roteamento.
`title`	Sim	Descrição curta em inglês (não localizada).
`status`	Sim	Código HTTP repetido no body para conveniência.
`detail`	Sim	Mensagem legível para o desenvolvedor.
`instance`	Sim	Path da requisição que causou o erro.
`errors`	Não	Lista de erros por campo (apenas em erros de validação).
`requestId`	Não	ID de correlação para suporte. Inclua ao abrir um chamado.

Catálogo de erros

`type` URI	Status	Quando ocorre
`urn:vestiai:error:validation`	400	Body malformado, campo obrigatório ausente, valor fora do enum
`urn:vestiai:error:unauthorized`	401	Sem credencial ou credencial inválida/expirada
`urn:vestiai:error:payment_required`	402	Créditos insuficientes para a operação
`urn:vestiai:error:forbidden`	403	Recurso existe mas o plano/permissão não permite acesso
`urn:vestiai:error:not_found`	404	Recurso não encontrado ou não pertence ao caller
`urn:vestiai:error:conflict`	409	`Idempotency-Key` usada em rota diferente; requisição concorrente com mesma chave
`urn:vestiai:error:rate_limit`	429	Limite de requisições da API key atingido (por minuto ou por dia)
`urn:vestiai:error:internal`	500	Erro inesperado no servidor

O plugin de idempotência emite 422 com type: urn:vestiai:error:idempotency_key_reuse quando a mesma Idempotency-Key é reutilizada com um body diferente.

Erros por status

400 Bad Request

Falha de validação de schema ou erro de regra de negócio. O campo errors lista os campos inválidos quando disponível:

{
  "type": "urn:vestiai:error:validation",
  "title": "Validation Error",
  "status": 400,
  "detail": "The request data is invalid.",
  "instance": "/api/v1/generations",
  "errors": [
    { "field": "clothingUploadIds", "message": "Expected array" }
  ]
}

401 Unauthorized

Bearer token ausente, expirado ou revogado. Verifique se o header Authorization: Bearer sk_live_... está presente e se a chave não foi revogada.

402 Payment Required

Créditos insuficientes. Recarregue créditos ou aguarde o reset do período de billing.

403 Forbidden

O recurso existe mas o plano não permite acesso. Exemplos: webhooks exigem plano pago; operações de gerenciamento de API keys exigem sessão autenticada.

404 Not Found

O recurso não existe ou pertence a outro usuário. Para geração, modelo ou upload que você não possui, a resposta é sempre 404 (nunca 403), para não vazar a existência de recursos de terceiros.

409 Conflict

Dois cenários:

Idempotency-Key enviada para uma rota diferente da original.
Tentativa concorrente com a mesma Idempotency-Key enquanto a primeira ainda está em processamento.

422 Unprocessable Entity

Idempotency-Key reutilizada com um body diferente do original. Gere uma nova chave para essa operação.

429 Too Many Requests

Limite de requisições atingido. O header retry-after indica quantos segundos aguardar (fixo em 60s). Veja Rate limits para detalhes.

500 Internal Server Error

Erro inesperado. O body em produção não expõe mensagem interna. Inclua o requestId ao reportar ao suporte.

Boas práticas

Roteie erros pelo campo type, nunca pelo texto de detail.
Armazene o requestId em seus logs sempre que ele estiver presente.
Para 429, respeite o valor de retry-after antes de retentar.
Para 422 com idempotency_key_reuse, gere um novo UUID antes de reenviar.
Trate 5xx com backoff exponencial; não reenvie imediatamente.

Veja também: Autenticacao para entender quando 401 e 403 se aplicam, e Rate limits para o comportamento completo de 429.