> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ya.works/llms.txt
> Use this file to discover all available pages before exploring further.

# Tratamento de Erros

> Entenda as respostas de erro da API e como tratá-las

# Tratamento de Erros

Quando uma requisição falha, a API retorna um objeto JSON com uma estrutura consistente.

## Formato de Erro

```json theme={null}
{
  "type": "ErrorType",
  "detail": "Descrição legível do que deu errado"
}
```

| Campo | Descrição |
| - | - |
| `type` | Identificador de erro legível por máquina |
| `detail` | Explicação legível por humanos |

## Códigos de Erro

| Status | Tipo | Quando Ocorre |
| - | - | - |
| 400 | `ValueError` | Parâmetros de consulta inválidos (ex. `limit` > 100) |
| 401 | `UnauthorizedError` | API key ausente, inválida, expirada ou revogada |
| 402 | `InsufficientFundsError` | A conta não pode pagar a mensagem — apenas em `POST /v1/template-messages`. Veja [Carrinho Abandonado](/pt/outbound/cart-abandonment) |
| 403 | `ForbiddenError` | A key não tem o escopo que o endpoint exige — ver [Autenticação](/pt/authentication) |
| 404 | `NotFoundError` | O recurso solicitado não existe |
| 422 | `ValidationError` | O body da requisição tem campos inválidos ou ausentes |
| 429 | `RateLimitExceededError` | Limite de requisições excedido — ver [Rate Limiting](/pt/rate-limiting) |
| 500 | `InternalServerError` | Erro inesperado do servidor |
| 502 | `UpstreamError` | Um serviço interno falhou. Tente novamente mais tarde |

## Exemplos

<AccordionGroup>
  <Accordion title="400 Bad Request">
    ```json theme={null}
    {
      "type": "ValueError",
      "detail": "limit must not exceed 100"
    }
    ```

    **Solução:** Verifique seus parâmetros de consulta. `limit` deve estar entre 1 e 100, e `page` deve ser 1 ou maior.
  </Accordion>

  <Accordion title="401 Unauthorized">
    ```json theme={null}
    {
      "type": "UnauthorizedError",
      "detail": "Invalid or missing API key"
    }
    ```

    **Solução:** Verifique que o header `X-API-Key` está presente e contém uma key válida e ativa.
  </Accordion>

  <Accordion title="403 Forbidden">
    ```json theme={null}
    {
      "type": "ForbiddenError",
      "detail": "Missing required scope: orders:read"
    }
    ```

    **Solução:** Sua key é válida mas não tem o escopo que esse endpoint exige. Hoje as keys são criadas com acesso completo, então esse erro não deveria aparecer; se você vê-lo, entre em contato com o suporte. Ver [Autenticação](/pt/authentication).
  </Accordion>

  <Accordion title="404 Not Found">
    ```json theme={null}
    {
      "type": "NotFoundError",
      "detail": "Order 99999 not found"
    }
    ```

    **Solução:** Verifique que o ID do recurso existe e pertence à sua conta de merchant.
  </Accordion>

  <Accordion title="429 Too Many Requests">
    ```json theme={null}
    {
      "type": "RateLimitExceededError",
      "detail": "Rate limit exceeded"
    }
    ```

    **Solução:** Espere o tempo indicado no header `Retry-After` antes de tentar novamente. Ver [Rate Limiting](/pt/rate-limiting) para boas práticas.
  </Accordion>

  <Accordion title="422 Validation Error">
    <Warning>
      Erros 422 usam um formato diferente: `detail` é um **array de objetos** (formato Pydantic/FastAPI), não uma string.
    </Warning>

    ```json theme={null}
    {
      "detail": [
        {
          "loc": ["body", "option_values"],
          "msg": "List should have at least 1 item",
          "type": "too_short"
        }
      ]
    }
    ```

    | Campo | Descrição |
    | - | - |
    | `loc` | Localização do campo que falhou (ex. `["body", "name"]`) |
    | `msg` | Descrição do erro de validação |
    | `type` | Tipo de erro do Pydantic (não é o mesmo `type` do formato padrão) |

    **Solução:** Verifique o body da sua requisição. Consulte o [API Reference](/api-reference) para ver os campos obrigatórios.
  </Accordion>

  <Accordion title="502 Bad Gateway">
    ```json theme={null}
    {
      "type": "UpstreamError",
      "detail": "An internal service error occurred. Please try again later."
    }
    ```

    **Solução:** Um serviço interno falhou. Sua requisição é válida — tente novamente após alguns segundos. Se persistir, entre em contato com o suporte.
  </Accordion>

  <Accordion title="500 Internal Server Error">
    ```json theme={null}
    {
      "type": "InternalServerError",
      "detail": "Internal server error"
    }
    ```

    **Solução:** Este é um problema do servidor. Tente novamente após um breve delay. Se o problema persistir, entre em contato com o suporte.
  </Accordion>
</AccordionGroup>

## Tratando Erros no Código

<CodeGroup>
  ```python Python theme={null}
  import httpx

  response = httpx.get(
      "https://api.ya.onl/v1/orders",
      headers={"X-API-Key": "yv_live_v1_sua_api_key"},
  )

  if response.status_code == 200:
      orders = response.json()["data"]
  elif response.status_code == 429:
      retry_after = int(response.headers["Retry-After"])
      print(f"Rate limited. Retry in {retry_after}s")
  else:
      error = response.json()
      print(f"Error [{response.status_code}]: {error['type']} - {error['detail']}")
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.ya.onl/v1/orders", {
    headers: { "X-API-Key": "yv_live_v1_sua_api_key" },
  });

  if (response.ok) {
    const { data: orders } = await response.json();
  } else if (response.status === 429) {
    const retryAfter = response.headers.get("Retry-After");
    console.log(`Rate limited. Retry in ${retryAfter}s`);
  } else {
    const error = await response.json();
    console.error(`Error [${response.status}]: ${error.type} - ${error.detail}`);
  }
  ```
</CodeGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.