Skip to main content

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "The 'engine' field is required"
  }
}

HTTP Status Codes

StatusMeaningWhat to do
400Bad RequestFix request parameters
401UnauthorizedCheck API key
402Payment RequiredAdd credits
403ForbiddenCheck permissions
404Not FoundVerify run ID
409ConflictIdempotency collision
500Server ErrorRetry with backoff
502Bad GatewayUpstream failed, retry
503Service UnavailableEngine down, retry later

SDK Exceptions

Both SDKs throw typed exceptions you can catch:
from subconscious import Subconscious
from subconscious.errors import (
    SubconsciousError,    # Base class
    AuthenticationError,  # 401
    ValidationError,      # 400
    NotFoundError,        # 404
)
import os

client = Subconscious(api_key=os.environ.get("SUBCONSCIOUS_API_KEY"))

try:
    run = client.run(
        engine="tim-gpt",
        input={"instructions": "Hello"},
        options={"await_completion": True},
    )
except AuthenticationError:
    print("Invalid API key")
except ValidationError as e:
    print(f"Bad request: {e.message}")
except SubconsciousError as e:
    print(f"Error {e.status}: {e.code} - {e.message}")
Exception properties:
  • code — Error type ("invalid_request", "authentication_failed", etc.)
  • status — HTTP status code
  • message — Human-readable message
  • details — Additional context (validation errors)

Retry Logic

Retry on 5xx errors with exponential backoff:
import time
import os
from subconscious import Subconscious
from subconscious.errors import SubconsciousError

client = Subconscious(api_key=os.environ.get("SUBCONSCIOUS_API_KEY"))

def run_with_retry(instructions, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.run(
                engine="tim-gpt",
                input={"instructions": instructions},
                options={"await_completion": True},
            )
        except SubconsciousError as e:
            if e.status < 500 or attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

run = run_with_retry("Summarize the news")

Run-Level Errors

Runs can fail after being accepted. Check the status field:
run = client.run(
    engine="tim-gpt",
    input={"instructions": "Your task"},
    options={"await_completion": True},
)

match run.status:
    case "succeeded":
        print(run.result.answer)
    case "failed":
        print(f"Failed: {run.error.message}")
    case "timed_out":
        print("Timed out")
    case "canceled":
        print("Canceled")

Quick Reference

ErrorCodeFix
Missing API key401Add Authorization: Bearer sk-... header
Invalid API key401Check key is active in dashboard
No credits402Add credits at subconscious.dev
Run not found404Verify run ID exists
Bad request400Check required fields and types
Engine down503Retry in a few minutes