Errors

A request failed and you want to know why, whether to retry it, and whether it cost anything. Every error comes with an HTTP status, a code that names the exact cause, the field at fault when there is one, and a request id. This page lists every error with its fix, gives you a retry loop to copy, and explains why failed requests are never charged.

At a glance

• Branch on error.code. It names the exact cause; error.message explains it in words for people.
• Retry only 429 rate_limit_exceeded, 502 and 503. Wait for Retry-After when the response sends it, otherwise back off exponentially with jitter.
• Every other error comes back the same way until you change the request, the key, your credit or your limits, so do not retry it.
• Failed requests are never charged, and they do not count toward your tokens per minute.
• Log request_id with every failure and include it when you write to support.
• Use a client timeout of 120 seconds, and retry 503 model_warming_up after its Retry-After: the first request after a quiet period finds Clara starting up.

The error object

Every error has the same JSON body. This request sends a choice question with only one option, so it fails validation. You can run it with any key on Tier 1 or above: it is rejected before anything runs or is charged. (A Tier 0 key gets 402 insufficient_credit first.)

curl -i https://api.saanora.com/v1/decisions \
  -H "Authorization: Bearer $SAANORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "clara-1",
    "state": "Customer asks why they were charged twice this month.",
    "questions": {
      "team": {
        "type": "choice",
        "instructions": "Which team should own this?",
        "criteria": { "billing": "Handles invoices, charges and refunds" }
      }
    }
  }'

x-request-id: req_5b0c2e8f9a1d4c7b3e6f8a20
content-type: application/json

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_criteria",
    "message": "choice needs criteria with 2 to 255 options",
    "param": "questions.team.criteria"
  },
  "request_id": "req_5b0c2e8f9a1d4c7b3e6f8a20"
}

The same errors and body apply to POST /v1/decisions and POST /v1/systemone, except missing_model: /v1/systemone uses clara-1 when model is left out. GET /v1/models can return the 401 and 503 errors.

Status codes

The status tells you which kind of problem you have and whether a retry can help.

Error codes

Each table covers one kind of failure. When a cause involves a specific field, error.param points at it.

Request errors (400, 413, 422)

The request itself needs to change. Sending it again unchanged returns the same error.

Authentication errors (401)

The key is missing or not accepted. See Authentication for how to send it.

Credit and limit errors (402, 429)

The request is fine, but your organization or project cannot run it right now. Only rate_limit_exceeded clears by waiting, within a minute at most. See Billing and credit and Rate limits.

Model errors (404, 502, 503)

A 404 means the model id is wrong. A 502 means the model was called but did not return answers. A 503 model_warming_up means Clara is starting after a quiet period. None is charged, and the 502 and 503 are safe to retry.

Service errors (503)

A platform service the request depends on was briefly unavailable. Nothing ran, so retrying with backoff is safe.

What you are never charged for

You pay only for requests that return 200. No error on this page is charged, including 502 model_unavailable and an invalid_request rejected by the model.

This is how it works. Before the model runs, the platform places a hold on your credit large enough for the worst case. If the request succeeds, the exact cost is deducted and reported in usage.cost_usd. If it fails, nothing is deducted. If the hold cannot be placed at all, you get 402 insufficient_credit and the model never runs.

• Refused before the model runs (every code except model_unavailable, model_warming_up and invalid_request): nothing ran, nothing is charged.
• Failed after the model was called (502 model_unavailable, 503 model_warming_up, invalid_request): no answers came back, nothing is charged.
• Tokens per minute: failed and refused requests do not count toward it. The limit counts billed tokens only, the same number as usage.input_tokens.

So retrying an error response costs nothing extra: you pay once, for the attempt that returns answers. A client-side timeout is different, because the request can still finish and be billed; see Cold starts and timeouts.

Retry temporary errors

Only these failures are temporary. Retry them, and nothing else:

• 429 rate_limit_exceeded: wait the number of seconds in the Retry-After header, then retry. Add up to a second of random jitter so your workers do not all come back at the same moment.
• 503 model_warming_up: consistent mode is still starting after a quiet period. Wait the number of seconds in Retry-After, then retry; it is ready about 50 seconds after fast mode.
• Other 502 and 503 errors: retry with exponential backoff and full jitter: wait a random time between 0 and 1 s, then up to 2 s, 4 s, 8 s, capped at 30 s.
• Network errors and timeouts where no response arrived: retry with the same backoff.

Do not retry anything else: 400, 401, 402, 404, 413, 422 and 429 project_spend_limit fail the same way until you change the request, the key, your credit or the limit. Stop after a fixed number of attempts (6 in the examples below, about 31 seconds of backoff at most, plus any Retry-After) and surface the error with its request_id.

A rate-limited response looks like this. Retry-After is a whole number of seconds; x-ratelimit-reset-requests says when a request slot frees up.

retry-after: 7
x-ratelimit-limit-requests: 300
x-ratelimit-remaining-requests: 0
x-ratelimit-reset-requests: 7s
x-request-id: req_9d41a7c03e2b6f58a1c4e7d2

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "300 requests per minute on tier 1; lifetime top-ups raise it",
    "param": null
  },
  "request_id": "req_9d41a7c03e2b6f58a1c4e7d2"
}

Both examples below wrap POST /v1/decisions in a decide function that retries as described, returns the parsed decision on success, and raises an error carrying status, code, param and the request id otherwise. Set SAANORA_API_KEY in your environment before running them. The Python version needs pip install requests. The TypeScript version needs Node 18 or later (for fetch and AbortSignal.timeout) and runs as an ES module, for example saved as decide.mts and run with npx tsx decide.mts.

import os
import random
import time

import requests

API_URL = "https://api.saanora.com"
RETRYABLE = {429, 502, 503}


class SaanoraError(Exception):
    """An error response from the API, with the fields you branch on."""

    def __init__(self, status, error, request_id):
        self.status = status
        self.code = error.get("code")
        self.param = error.get("param")
        self.request_id = request_id
        super().__init__(f"{status} {self.code}: {error.get('message')} (request {request_id})")


def backoff(attempt, base=1.0, cap=30.0):
    """Exponential backoff with full jitter: a random wait of up to 1 s, 2 s, 4 s, ... capped at 30 s."""
    return random.uniform(0, min(cap, base * 2 ** (attempt - 1)))


def decide(body, max_attempts=6):
    for attempt in range(1, max_attempts + 1):
        last = attempt == max_attempts
        try:
            r = requests.post(
                f"{API_URL}/v1/decisions",
                headers={"Authorization": f"Bearer {os.environ['SAANORA_API_KEY']}"},
                json=body,
                timeout=120,  # the first request after a quiet period can take a while
            )
        except (requests.ConnectionError, requests.Timeout):
            if last:
                raise
            time.sleep(backoff(attempt))  # no response arrived
            continue

        if r.ok:
            return r.json()

        try:
            payload = r.json()
        except ValueError:
            payload = {}
        error = payload.get("error") or {}
        request_id = payload.get("request_id") or r.headers.get("x-request-id")
        retryable = r.status_code in RETRYABLE and error.get("code") != "project_spend_limit"
        if not retryable or last:
            raise SaanoraError(r.status_code, error, request_id)

        retry_after = r.headers.get("Retry-After")
        if retry_after:
            time.sleep(float(retry_after) + random.uniform(0, 1))  # the server's wait, plus jitter
        else:
            time.sleep(backoff(attempt))


try:
    result = decide({
        "model": "clara-1",
        "state": "Order 4417 arrived with a cracked screen. The customer asks for a replacement.",
        "questions": {
            "damaged": {"type": "noul", "instructions": "Did the item arrive damaged?"},
        },
    })
    print(result["answers"]["damaged"]["noul"], result["usage"]["cost_usd"])
except SaanoraError as e:
    if e.code == "insufficient_credit":
        print("Out of credit: add some in Console > Billing")
    elif e.status in (400, 413, 422):
        print(f"Fix the request at {e.param}: {e}")
    raise

A decision changes nothing on your side, so repeating one is safe: a retried request returns a fresh decision about the same record.

Cold starts and timeouts

Clara scales down when idle, so after a quiet period it needs about a minute to start: the first request waits about 60–80 seconds and is then answered. Consistent mode follows about 50 seconds later; until then a consistent request gets 503 model_warming_up, never charged, with a Retry-After header saying how many seconds to wait. Retry after that wait, as the loop above does. Once it is running, Clara answers five questions about one record in about 0.1 s.

• Set your client timeout to 120 seconds. Check every layer between your code and the API: the HTTP client, any proxy, and any serverless function with its own time limit.
• Once Clara is running, the platform waits up to 120 seconds for an answer. If none comes, you get 502 model_unavailable, which is never charged, and the retry loop above retries it.
• The latency_ms field in a successful response is the model time, and the saanora-processing-ms header is the total time in the platform. If your client measured much more than that, the time went to the network or your own code.

Avoid errors before they happen

• Build request bodies with a JSON encoder, never by joining strings. This rules out invalid_json.
• Check questions in your own code before sending: a type of noul, choice or score; 2 to 255 options for choice; 2 to 255 levels for score; criteria left out or an object for noul; no more questions than your tier allows (32 on Tier 1, 64 from Tier 2).
• Read x-ratelimit-remaining-requests and x-ratelimit-remaining-tokens on each response and slow down before they reach 0.
• Call GET /v1/models when your service starts to confirm the model ids you use are live.
• Keep enough credit for the worst-case hold of your largest request. Credit never expires, so a buffer is never lost. See Billing and credit.
• Keep records under 16K tokens. Longer ones are not rejected, but they are shortened in the middle, which can remove the text a question depends on.

Debug a failed request

Log four things for every failure: the HTTP status, error.code, error.param and request_id. Together they tell you what failed, where, and which request it was.

If you cannot work out the cause, write to support@saanora.com with the request id and the full error body. For every request that reaches the model, including model_unavailable and invalid_request failures, the platform stores its metadata (time, organization, project, key, model, mode, status, number of questions, input tokens, latency, cost and request id), so support can find it from the id alone. Requests refused before the model runs are not stored, so for those also say when you sent the request.