Troubleshooting TypeSafe Jev API Errors: HTTP 401, 422, 429, and 529

When a TypeSafe Jev API request fails, the endpoint returns standard HTTP status codes accompanied by a JSON error body. Because Jev is a non-autoregressive decision model rather than a chat completion endpoint, failure causes differ markedly from traditional LLMs: you will not encounter output-token cutoffs, tool-call syntax errors, or streaming decode interruptions.

Failures stem primarily from upfront request structure violations (such as passing invalid primitive configurations), token context budget overflows, or concurrency throttling.

Error Diagnostic Matrix

HTTP Status	Primary Cause	Immediate Observable Symptom	Quick Fix
`401 Unauthorized`	Missing, malformed, or revoked API key	`Authorization` rejected before reaching inference workers	Set `TYPESAFE_API_KEY` in environment and test key in `console.typesafe.ai`
`422 Unprocessable Entity`	Malformed question, option bounds violated, missing `state`, or context exceeded	Immediate error details identifying invalid parameter or length overflow	Ensure `Choice` has 2–255 options, `Score` has 2–10 levels, `state` is present, and context stays within 64k total tokens (and 32k state + question)
`429 Too Many Requests`	Concurrency ceiling exceeded: > 1,200 req/min or > 250,000 tokens/sec	Requests throttled with `Retry-After` response header	Implement exponential backoff with jitter; batch questions into single calls
`529 Overloaded`	Inference service cluster temporarily overloaded	Temporary rejection during high-concurrency spikes	Retry with randomized exponential backoff
`500 Internal Error`	Unexpected server-side failure during processing	Unhandled internal exception	Retry with backoff; if persistent, contact TypeSafe support

Detailed Troubleshooting by Status Code

1. HTTP 422 Unprocessable Entity

HTTP 422 indicates that your request failed TypeSafe's upfront payload validation before reaching the model weights, or that the payload exceeded token limits.

Common Trigger: Option Boundaries Violations

Choice option count: TypeSafe enforces that a Choice must have at least 2 and at most 255 options. Passing an empty list, 1 option, or 256+ options causes immediate 422 rejection.
- Fix: If you have hundreds of categories, split your decision into a two-tiered hierarchy (first classify broad category, then specific sub-item).
Score level count: Score strictly requires between 2 and 10 ordered criteria levels. Passing fewer than 2 or more than 10 levels returns 422.
- Fix: Compress rubrics into 3 to 5 clear tiers.

Common Trigger: Missing Required Fields

Omitting state, model, or questions in the request body returns 422.
- Fix: Ensure the payload contains "model", a populated "state" (string, JSON object, or list of strings), and at least one defined question in "questions".

Common Trigger: Conversational Chat Payload

Sending messages formatted for OpenAI or Anthropic chat completions (messages: [{"role": "user", ...}]) to POST /v1/systemone fails with 422.
- Fix: Restructure the payload into state and questions.

Common Trigger: Token Context Budget Overflows

Jev enforces two distinct token limits per request:

Total Request Budget: 64,000 tokens maximum across state and all question definitions combined.
State & Question Boundary: state combined with the single longest question cannot exceed 32,000 tokens.

Fix: Pre-filter state in application code before invoking Jev:

# Strip unnecessary data before sending to Jev
cleaned_state = {
    "summary": ticket["summary"],
    "error_snippet": ticket["raw_log"][:2000],  # Bound log size
    "user_tier": ticket["user"]["tier"]
}

2. HTTP 401 Unauthorized

HTTP 401 occurs when authentication credentials are invalid or missing.

Diagnosis Steps

Verify the environment variable name: the official Python and TypeScript SDKs look for TYPESAFE_API_KEY by default.

If calling via raw curl or HTTP client, ensure the header uses standard Bearer syntax:

curl -H "Authorization: Bearer ts_live_..." -H "Content-Type: application/json" https://api.typesafe.ai/v1/systemone

Verify your key in console.typesafe.ai. If the key was rotated or project permissions were revoked, generate a fresh key.

3. HTTP 429 Too Many Requests

TypeSafe enforces early-access concurrency envelopes:

1,200 requests per minute (RPM) per organization.
250,000 tokens per second (TPS) throughput ceiling.

The State Multiplier Trap

Because rate limits include token throughput (TPS), sending large state payloads dramatically accelerates 429 throttling:

If your state is 500 tokens, 1,200 RPM consumes only 10,000 tokens/sec (well below the 250k ceiling).
If your state is 25,000 tokens, running just 11 requests per second consumes 275,000 tokens/sec, triggering immediate 429 rate limiting even though you are well below the 1,200 RPM request ceiling.

Handling 429 in Code

TypeSafe includes a Retry-After response header on 429 responses. In the official Python SDK, TypeSafeRateLimitError exposes a retry_after_ms attribute. Always implement exponential backoff with jitter:

import time
import random
from typesafe_sdk import TypeSafeClient
from typesafe_sdk.exceptions import TypeSafeRateLimitError, TypeSafeOverloadedError

client = TypeSafeClient()

def call_jev_with_retry(state, questions, max_retries=4):
    for attempt in range(max_retries):
        try:
            return client.system_one(
                model="jev-latest",
                state=state,
                questions=questions
            )
        except (TypeSafeRateLimitError, TypeSafeOverloadedError) as e:
            if attempt < max_retries - 1:
                # Use server-suggested retry duration if available, or exponential backoff
                server_delay = getattr(e, "retry_after_ms", None)
                if server_delay:
                    sleep_time = (server_delay / 1000.0) + random.uniform(0.01, 0.05)
                else:
                    sleep_time = (0.1 * (2 ** attempt)) + random.uniform(0.02, 0.08)
                time.sleep(sleep_time)
                continue
            raise e

4. HTTP 529 Overloaded and HTTP 500

529 Overloaded: Indicates that the inference cluster is experiencing temporary traffic saturation. Unlike fatal client errors, 529 is transient; clients should retry with randomized exponential backoff.
500 Internal Server Error: Indicates an unexpected server-side error during evaluation. The Python SDK raises TypeSafeInternalServerError. If errors persist after backoff retries, verify platform status or contact TypeSafe support.

Gateway-Specific Considerations

Direct TypeSafe API (https://api.typesafe.ai/v1/systemone): Direct calls return TypeSafe's native JSON error format with field-level validation messages and minimal network overhead.
Third-Party Gateways (e.g. OpenRouter): When accessing Jev via gateway providers, requests are subject to the gateway's routing, account balance, and error response formatting. If credentials or credits expire at the gateway layer, the gateway may return its own platform-specific error responses.

Related Context

Jev API Reference & Schema Specification

implementation

Jev Rate Limits & Concurrency Ceilings

concept

Structuring State for TypeSafe Jev

workflow