Manejo de Errores

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

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

Formato de Error

{
  "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
403	`ForbiddenError`	La key no tiene el alcance que el endpoint requiere — ver Autenticación
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
500	`InternalServerError`	Error inesperado del servidor
502	`UpstreamError`	Un servicio interno falló. Reintenta más tarde

Ejemplos

400 Bad Request

{
  "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.

401 Unauthorized

{
  "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.

403 Forbidden

{
  "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.

404 Not Found

{
  "type": "NotFoundError",
  "detail": "Order 99999 not found"
}

Solución: Verifica que el ID del recurso existe y pertenece a tu cuenta de merchant.

429 Too Many Requests

{
  "type": "RateLimitExceededError",
  "detail": "Rate limit exceeded"
}

Solución: Espera el tiempo indicado en el header Retry-After antes de reintentar. Ver Rate Limiting para buenas prácticas.

422 Validation Error

Los errores 422 usan un formato diferente al resto: detail es un array de objetos (formato Pydantic/FastAPI), no un string.

{
  "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 para ver los campos requeridos.

502 Bad Gateway

{
  "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.

500 Internal Server Error

{
  "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.

Manejar Errores en Código

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']}")