Authentication

All API requests require authentication via an API key. Keys are managed from your dashboard.

API Key Format

Osiris API keys follow the format:

sk-osiris-{32 hex characters}

Example: sk-osiris-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

Using Your API Key

Include your API key in the Authorization header as a Bearer token:

curl https://api.osiris.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-osiris-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hi"}]}'

Error Codes

The following HTTP status codes are returned for authentication and authorization errors:

Status	Name	Description
`401`	Unauthorized	Invalid or missing API key
`402`	Payment Required	Insufficient token balance
`403`	Forbidden	Model not allowed for this API key
`429`	Too Many Requests	Rate limit exceeded

Rate Limiting

API requests are rate-limited per API key using a sliding window algorithm. Rate limit information is included in the response headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Remaining requests in the current window
`X-RateLimit-Reset`	Unix timestamp when the rate limit window resets

When rate limited, the API returns a 429 status code with a Retry-After header indicating how many seconds to wait.

Error Handling Example

Here's how to handle authentication and rate limit errors in your application:

error-handling.ts

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-osiris-YOUR_KEY",
  baseURL: "https://api.osiris.ai/v1",
});

try {
  const response = await client.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello!" }],
  });
  console.log(response.choices[0].message.content);
} catch (error) {
  if (error instanceof OpenAI.APIError) {
    switch (error.status) {
      case 401:
        console.error("Invalid API key");
        break;
      case 402:
        console.error("Insufficient balance — top up your account");
        break;
      case 403:
        console.error("Model not allowed for this key");
        break;
      case 429:
        const retryAfter = error.headers?.["retry-after"];
        console.error(`Rate limited. Retry after ${retryAfter}s`);
        break;
      default:
        console.error(`API error: ${error.status} ${error.message}`);
    }
  }
}