Errores

Toda llamada fallida devuelve la misma forma JSON y un estado HTTP estándar. El SDK convierte cada uno en una excepción de Python, así su código maneja un significado, no un número.

El cuerpo del errorCopiar el enlace

Los errores siguen el RFC 9457 y se envían como application/problem+json:

{
  "type": "https://klarety.ai/problems/too-many-requests",
  "title": "Too many requests",
  "status": 429,
  "detail": "slow down and retry in 12s",
  "instance": "/v1/sql"
}

Códigos de estadoCopiar el enlace

Cómo los lanza el SDKCopiar el enlace

Todas las excepciones del SDK heredan de KlaretyError, y se importan desde klarety.

Un manejo cuidadosoCopiar el enlace

from klarety import (
    AuthError,
    ConflictError,
    InsufficientCreditsError,
    KlaretyError,
    Nexus,
    OverBudgetError,
    RefusedError,
    ServiceError,
)

try:
    with Nexus.connect() as nexus:
        result = nexus.sql("SELECT COUNT(*) AS n FROM orders")
        print(result.rows)
except AuthError:
    print("Sign-in failed: check or replace the API key.")
except InsufficientCreditsError:
    print("Out of credits.")
except OverBudgetError as over:
    print(f"Over a plan limit or rate: {over}")
except RefusedError as refused:
    print(f"Not allowed: {refused}")
except ConflictError:
    print("Changed since read: read again, then retry.")
except ServiceError as failed:
    print(f"Klarety could not answer, try later: {failed}")
except KlaretyError as other:
    print(f"Klarety error: {other}")

El orden importa: capture primero las excepciones más específicas.

Lo que el SDK reintenta por ustedCopiar el enlace

Rara vez necesita su propio ciclo de reintentos.

• Las lecturas (GET) se reintentan hasta tres veces ante 502, 503 y 504, con una espera corta.
• Las respuestas de ocupado o de límite de solicitudes se esperan en cualquier llamada, respetando Retry-After, hasta por cinco minutos. No se ejecutó nada, así que es seguro.
• Las sentencias SQL llevan un ID, así que una sentencia reenviada se ejecuta una sola vez.
• Las demás escrituras (POST, PUT, PATCH, DELETE) nunca se reintentan, porque repetir una podría gastar créditos dos veces.

Reintentos con HTTP directoCopiar el enlace

Si llama a la API directamente:

1. Reintente solo ante 429, 503 y 500.
2. Espere los segundos del encabezado Retry-After cuando aparece; si no, espere un tiempo creciente con variación aleatoria.
3. Reintente una escritura solo si es seguro ejecutarla dos veces, o si lleva su propio ID (statement_id en /v1/sql, write_id en ediciones de filas).

Próximos pasosCopiar el enlace

• Límites y límites de solicitudes para ver qué provoca 429 y 413.
• Autenticación para 401.
• Referencia de la API para todos los endpoints.