Errors

Every failed API call returns the same JSON shape and a standard HTTP status. The SDK turns each into a Python exception, so your code handles a meaning, not a number.

The error bodyCopy Anchor Link

Errors follow RFC 9457 and are sent as 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"
}

Status codesCopy Anchor Link

How the SDK raises themCopy Anchor Link

All SDK exceptions inherit from KlaretyError, and you import them from klarety.

A careful handlerCopy Anchor Link

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

Order matters: catch the more specific exceptions first.

What the SDK retries for youCopy Anchor Link

You rarely need your own retry loop.

• Reads (GET) are retried up to three times on 502, 503 and 504, with a short backoff.
• Busy and rate-limited answers are waited out on any call, honouring Retry-After, for up to five minutes. Nothing ran, so this is safe.
• SQL statements carry an ID, so a resent statement runs once.
• Other writes (POST, PUT, PATCH, DELETE) are never retried, because replaying one could spend credits twice.

Retrying with raw HTTPCopy Anchor Link

If you call the API directly:

1. Retry only on 429, 503 and 500.
2. Wait the Retry-After header's seconds when it is present; otherwise back off with random jitter.
3. Retry a write only if it is safe to run twice, or carries its own ID (statement_id on /v1/sql, write_id on row edits).

Next stepsCopy Anchor Link

• Limits and rate limits to see what triggers 429 and 413.
• Authentication for 401.
• API reference for every endpoint.