Error Codes

TokenSupernova uses standard HTTP status codes and returns errors in OpenAI-compatible format.

Error Response Format

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

HTTP Status Codes

Code	Meaning	Action
200	Success	Your request was processed
400	Bad Request	Check your request body for errors
401	Unauthorized	Invalid or missing API key
402	Payment Required	Insufficient balance — top up your account
404	Not Found	Model or endpoint doesn’t exist
429	Rate Limited	Slow down your requests
500	Server Error	Something went wrong on our side — retry
503	Service Unavailable	Model temporarily overloaded — retry with backoff

Common Errors

401 — Invalid API Key

{
  "error": {
    "message": "Invalid API key provided. Check your key at api.tokensupernova.com/console.",
    "type": "auth_error",
    "code": "invalid_api_key"
  }
}

Fix: Verify your API key starts with tsn_live_ and was copied correctly.

402 — Insufficient Balance

{
  "error": {
    "message": "Insufficient balance. Top up at api.tokensupernova.com/console.",
    "type": "billing_error",
    "code": "insufficient_balance"
  }
}

Fix: Add credits to your account via the console.

429 — Rate Limit

{
  "error": {
    "message": "Rate limit exceeded. Retry after 60 seconds.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

Fix: Implement exponential backoff. See Rate Limits →

500 — Server Error

{
  "error": {
    "message": "Internal server error. Please try again.",
    "type": "server_error",
    "code": "internal_error"
  }
}

Fix: Retry with exponential backoff. If the issue persists, contact support.

Retry Strategy

We recommend implementing exponential backoff for 429 and 5xx errors:

import time
import random

def retry_with_backoff(fn, max_retries=5, base_delay=1):
    for attempt in range(max_retries):
        try:
            return fn()
        except RateLimitError:
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            time.sleep(delay)
    raise Exception("Max retries exceeded")