# Erros

Cada erro é um JSON com uma mensagem legível por humanos `error` e um `code` estável. Baseie-se no `code`, e não na mensagem.

```json
{ "error": "No credits left. Top up your developer wallet to continue.", "code": "NO_CREDITS" }
```

## Gerar erros

| HTTP | código | O que aconteceu | Tentar novamente? |
|---|---|---|---|
| 400 | `BAD_INPUT` | Não foi possível ler o corpo do texto | Não, corrige o pedido |
| 400 | `NO_PERSON` | A imagem da pessoa está em falta, é ilegível ou não está num formato suportado | Não, envie uma imagem válida |
| 400 | `NO_GARMENT` | A imagem da peça de roupa está em falta, é ilegível ou o `garment_url` está bloqueado | Não, envie uma imagem válida ou um URL público em https |
| 401 | `NO_KEY` | Sem cabeçalho `X-API-KEY` | Não |
| 401 | `INVALID_KEY` | Chave incorreta ou revogada | Não, verifica a chave no painel de instrumentos |
| 402 | `NO_CREDITS` | Créditos adquiridos esgotados | Não, [comprar créditos](/pricing#developer-api) |
| 402 | `QUOTA_EXCEEDED` | A franquia gratuita foi esgotada | Não, comprar créditos |
| 402 | `KEY_LIMIT_REACHED` | Esta chave API atingiu o seu limite de crédito mensal. O corpo da mensagem inclui `used` e `limit` | Não, espera até ao dia 1 (UTC) ou usa uma chave com um limite mais elevado |
| 402 | `FREE_TRIAL_USED` | O período de avaliação gratuita já foi utilizado neste dispositivo | Não, comprar créditos |
| 403 | `DEVICE_BANNED` | Este dispositivo foi bloqueado devido a uso indevido | Não, contacte o apoio ao cliente |
| 400 | `BAD_IDEMPOTENCY_KEY` | A `Idempotency-Key` está vazia, é demasiado longa ou contém espaços | Não, corrige o cabeçalho |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | Uma solicitação com esta chave ainda está em execução. Não foi cobrado nada | Sim, após o `Retry-After` |
| 409 | `IDEMPOTENCY_REPLAY` | Esta chave já funcionou. Não foi cobrado nada. | Não, a primeira resposta incluía a imagem |
| 409 | `IDEMPOTENCY_MISMATCH` | Esta chave foi utilizada com diferentes imagens | Não, usa uma chave nova |
| 413 | `IMAGE_TOO_LARGE` | Uma imagem tem mais de 15 MB | Não, primeiro reduz a escala |
| 422 | `CONTENT_FILTERED` | Bloqueado devido à moderação de conteúdos. Crédito reembolsado | Não, usa imagens diferentes |
| 429 | `RATE_LIMITED` | Demasiados pedidos | Sim, após `Retry-After` segundos |
| 500 | `GENERATION_FAILED` | O motor avariou. O crédito foi reembolsado | Sim, uma vez |

## Tarefas assíncronas e lotes

| HTTP | código | O que aconteceu | Tentar novamente? |
|---|---|---|---|
| 400 | `BAD_WEBHOOK_URL` | `webhook_url` não é um URL `https` público | Não, corrige o URL |
| 400 | `BATCH_TOO_LARGE` | Mais de 500 itens, ou mais de 10 no modo de teste | Não, divide o lote |
| 402 | `ASYNC_NEEDS_CREDITS` | As tarefas assíncronas e os lotes utilizam os créditos adquiridos | Não, compra créditos ou utiliza `POST /generate` |
| 429 | `TOO_MANY_JOBS` | Já existem 50 tarefas assíncronas a ser executadas na conta | Sim, após `Retry-After` |
| 500 | `JOB_CREATE_FAILED`, `BATCH_CREATE_FAILED` | Não foi possível criá-lo. Os créditos foram reembolsados | Sim |

Uma tarefa que falha após ter sido aceite apresenta o código de erro `error.code`, tanto na própria tarefa como no webhook `generation.failed`: `CONTENT_FILTERED`, `GENERATION_FAILED` ou `INPUT_FETCH_FAILED` (não foi possível descarregar o URL de uma imagem). O crédito correspondente é reembolsado. Os itens do lote cancelados apresentam o estado `CANCELLED`.

## Outros parâmetros de avaliação

| Ponto final | HTTP | código | Tentar novamente? |
|---|---|---|---|
| `GET /credits` | 500 | `CREDITS_UNAVAILABLE` | Sim |
| `GET /results/:id` | 404 | `NOT_FOUND` (desconhecido, não é seu ou tem mais de 7 dias) | Não |
| `DELETE /customers/:id` | 500 | `DELETE_FAILED` (não foi apagado nada) | Sim |
| `DELETE /results/:id` | 404 | `NOT_FOUND` | Não |
| `DELETE /results/:id` | 500 | `DELETE_FAILED` | Sim |

## Manuseamento recomendado

```js
async function tryOn(form) {
  for (let attempt = 1; attempt <= 2; attempt++) {
    const res = await fetch("https://www.tryoncloud.com/api/v1/generate", {
      method: "POST",
      headers: { "X-API-KEY": process.env.TRYONCLOUD_API_KEY },
      body: form,
      signal: AbortSignal.timeout(120_000),
    })
    if (res.ok) return Buffer.from(await res.arrayBuffer())

    const { code, error } = await res.json()
    if (code === "RATE_LIMITED") {
      await new Promise((r) => setTimeout(r, Number(res.headers.get("Retry-After") || 5) * 1000))
      continue
    }
    if (code === "GENERATION_FAILED" && attempt === 1) continue // refunded, retry once
    throw new Error(`${code}: ${error}`) // 4xx: fix input or buy credits, do not loop
  }
  throw new Error("GENERATION_FAILED twice")
}
```

> **Aviso:** Nunca volte a tentar um código de erro `402` num ciclo. Isso significa que a conta ficou sem créditos.
