Response envelope

Every response from the LLM Prover API uses the same envelope:

{
  "ok": true,
  "request_id": "a1b2c3d4-...",
  "data": { ... }
}

On error:

{
  "ok": false,
  "request_id": "a1b2c3d4-...",
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE"
}

Always check ok first. Use code for programmatic handling. Use error for displaying to users or logging.

Error codes

HTTP	Code	Meaning	Action
400	`VALIDATION_ERROR`	Request body failed validation	Fix the request. Check the `error` field for which field failed.
400	`HARD_CAP_EXCEEDED`	Monthly spend hard cap reached	Top up or upgrade.
401	`UNAUTHORIZED`	Missing or invalid API key	Check your key. Revoked or expired keys return this.
402	`INSUFFICIENT_BALANCE`	Monthly allowance exhausted	Top up from the account page or upgrade your plan.
403	`TIER_REQUIRED`	Feature requires a higher tier	Upgrade your plan. The `error` field names the required tier.
404	`NOT_FOUND`	Resource does not exist or does not belong to your account	Check the ID.
409	`ASSET_IN_USE`	Cannot delete – resource is used by active benchmarks	Pass `confirmed_name` to force delete, or remove the dependency first.
429	`RATE_LIMIT_EXCEEDED`	Too many requests	Back off and retry. See Rate limits.
429	`KEY_LIMIT_REACHED`	Cannot create more API keys on your plan	Revoke an existing key or upgrade.
500	`INTERNAL_ERROR`	Unexpected server error	Retry once. If it persists, contact support with your `request_id`.

Handling errors in Python

resp = requests.post(f"{BASE_URL}/compare", headers=HEADERS, json=body)
data = resp.json()

if not data.get("ok"):
    code = data.get("code", "UNKNOWN")
    if code == "INSUFFICIENT_BALANCE":
        # prompt user to top up
    elif code == "RATE_LIMIT_EXCEEDED":
        # back off and retry
    elif code == "TIER_REQUIRED":
        # prompt user to upgrade
    else:
        raise RuntimeError(f"API error {code}: {data.get('error')}")

Provider errors

When a provider call fails inside a job (e.g. a model is temporarily unavailable), the job itself completes successfully but the affected model’s result has an error field set:

{
  "provider": "anthropic",
  "model": "claude-3-5-sonnet-20241022",
  "error": "Provider unavailable. Please try again.",
  "error_type": "unavailable"
}

Other results in the same job are unaffected. Check each result’s error field when processing job output.

What’s next

Fair usage – what triggers suspension
Async jobs – handling failed jobs