---
title: "Erros"
description: "O formato do erro e o que fazer com cada código."
source_url: "https://staging-hypio.doti.gg/docs/erros"
updated: "2026-11-11"
---

# Erros

O formato do erro e o que fazer com cada código.

## Formato

```json
{
  "error": {
    "code": "insufficient_credits",
    "message": "Saldo insuficiente.",
    "requiredCredits": 120,
    "availableCredits": 40
  }
}
```

Decida pelo `code`. A `message` é para gente e pode mudar.

## Códigos

| Status | `code` | O que fazer |
| --- | --- | --- |
| 400 | `invalid_json` | Corrija o JSON do corpo. |
| 401 | `unauthorized` | Confira a chave e o header `Authorization`. |
| 402 | `insufficient_credits` | Recarregue. O corpo traz `requiredCredits` e `availableCredits`. |
| 403 | `insufficient_scope` | Use uma chave com o escopo em `requiredScope`. |
| 403 | `account_suspended` | Fale com o suporte. |
| 404 | `not_found` | O recurso não existe ou é de outra organização. |
| 405 | `method_not_allowed` | Use um método do header `Allow`. |
| 409 | `conflict` | Estado incompatível. Leia de novo e decida. |
| 422 | `validation_error` | Corrija o campo em `field`. |
| 429 | `rate_limited` | Espere o `Retry-After`, em segundos. |
| 429 | `concurrency_limit` | Espere uma geração terminar. O corpo traz `limit`. |
| 500 | `internal_error` | Tente de novo com a mesma `Idempotency-Key`. |

## Novas tentativas

Repita só `429` e `5xx`, com espera crescente. Num `POST`, repita sempre com a mesma `Idempotency-Key` para não gerar e cobrar duas vezes.