Errores · Tessera

Formato del error

Todos los errores devueltos por la API siguen el envelope OpenAI: un body JSON con un campo error que contiene message, type y opcionalmente code y param.

Ejemplo de error

{
  "error": {
    "message": "Incorrect API key provided. You can find your API key in your welcome email.",
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "param": null
  }
}

Códigos HTTP

Código	Significado	Reintentar?
400	Request mal formado: JSON inválido, campo requerido faltante, parámetro fuera de rango	No — corrige el cliente
401	API key faltante o inválida	No — verifica la key
403	API key válida pero sin permiso para este recurso o modelo	No — contacta soporte
404	Modelo o endpoint no existe	No — corrige el `model` o la URL
413	Payload demasiado grande (audio >25 MB, contexto excesivo)	No — divide la entrada
422	Validación semántica falló (formato de audio no soportado, dimensiones inválidas)	No — corrige el cliente
429	Rate limit excedido	Sí, con backoff — ver /docs/api/rate-limits
500	Error interno del servidor	Sí, con backoff exponencial
502 / 503	Backend temporalmente no disponible (mantenimiento, GPU fría)	Sí, con backoff
504	Timeout en upstream (request muy largo)	Sí; considera reducir el contexto

Tipos de error en `error.type`

Tipo	Cuándo aparece
`invalid_request_error`	Body mal formado, parámetros incompatibles, formato no soportado
`authentication_error`	Key faltante o inválida (también 401)
`permission_error`	Key sin acceso al modelo o endpoint (403)
`rate_limit_error`	Cuota agotada en la ventana actual (429)
`api_error`	Error interno; típicamente transitorio (500)
`overloaded_error`	Backend saturado; reintenta con backoff (503)

Estrategia de reintentos

Solo reintenta sobre 429, 500, 502, 503 y 504. El resto son errores del cliente y no se resuelven con reintentos.
Backoff exponencial con jitter aleatorio: min(60, 2^attempt + random()) segundos. Detalle en /docs/api/rate-limits.
Honra el header Retry-After cuando esté presente — la API ya te dice cuánto esperar.
Después de 5 reintentos consecutivos sin éxito, escala a un alert o registro de fallos en lugar de seguir reintentando indefinidamente.

Cuándo contactar soporte

Para errores recurrentes que no se resuelven con reintentos, contacta a [email protected] incluyendo: timestamp UTC del error, id del request si está en headers, código y body del error, y el endpoint llamado. Tiempo de respuesta: <4 h hábiles en Pro, <1 h hábil en Scale, Slack compartido en Enterprise.