> ## 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.

# Manejo de Errores

> Entiende las respuestas de error de la API y cómo manejarlas

# Manejo de Errores

Cuando una petición falla, la API devuelve un objeto JSON con una estructura consistente.

## Formato de Error

```json theme={null}
{
  "type": "ErrorType",
  "detail": "Descripción legible de lo que salió mal"
}
```

| Campo | Descripción |
| - | - |
| `type` | Identificador de error legible por máquina |
| `detail` | Explicación legible por humanos |

## Códigos de Error

| Status | Tipo | Cuándo Ocurre |
| - | - | - |
| 400 | `ValueError` | Parámetros de consulta inválidos (ej. `limit` > 100) |
| 401 | `UnauthorizedError` | API key faltante, inválida, expirada o revocada |
| 402 | `InsufficientFundsError` | La cuenta no puede pagar el mensaje — sólo en `POST /v1/template-messages`. Ver [Carrito Abandonado](/outbound/cart-abandonment) |
| 403 | `ForbiddenError` | La key no tiene el alcance que el endpoint requiere — ver [Autenticación](/authentication) |
| 404 | `NotFoundError` | El recurso solicitado no existe |
| 422 | `ValidationError` | El body del request tiene campos inválidos o faltantes |
| 429 | `RateLimitExceededError` | Límite de peticiones excedido — ver [Rate Limiting](/rate-limiting) |
| 500 | `InternalServerError` | Error inesperado del servidor |
| 502 | `UpstreamError` | Un servicio interno falló. Reintenta más tarde |

## Ejemplos

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

    **Solución:** Verifica tus parámetros de consulta. `limit` debe estar entre 1 y 100, y `page` debe ser 1 o mayor.
  </Accordion>

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

    **Solución:** Verifica que el header `X-API-Key` esté presente y contenga una key válida y activa.
  </Accordion>

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

    **Solución:** Tu key es válida pero le falta el alcance que ese endpoint requiere. Hoy las keys se crean con acceso completo, así que este error no debería aparecer; si lo ves, contacta a soporte. Ver [Autenticación](/authentication).
  </Accordion>

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

    **Solución:** Verifica que el ID del recurso existe y pertenece a tu cuenta de merchant.
  </Accordion>

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

    **Solución:** Espera el tiempo indicado en el header `Retry-After` antes de reintentar. Ver [Rate Limiting](/rate-limiting) para buenas prácticas.
  </Accordion>

  <Accordion title="422 Validation Error">
    <Warning>
      Los errores 422 usan un formato diferente al resto: `detail` es un **array de objetos** (formato Pydantic/FastAPI), no un string.
    </Warning>

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

    | Campo | Descripción |
    | - | - |
    | `loc` | Ubicación del campo que falló (ej. `["body", "name"]`) |
    | `msg` | Descripción del error de validación |
    | `type` | Tipo de error de Pydantic (no es el mismo `type` del formato estándar) |

    **Solución:** Revisa el body de tu request. Consulta el [API Reference](/api-reference) para ver los campos requeridos.
  </Accordion>

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

    **Solución:** Un servicio interno falló. Tu request es válido — reintenta después de unos segundos. Si persiste, contacta a soporte.
  </Accordion>

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

    **Solución:** Este es un problema del servidor. Reintenta después de un breve delay. Si el problema persiste, contacta a soporte.
  </Accordion>
</AccordionGroup>

## Manejar Errores en 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_tu_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_tu_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.