Reference · Errors

Errors

Cosavu uses conventional HTTP response codes and returns a consistent JSON error shape for every failure. Both SDKs raise typed exception classes you can catch directly.

Error response shape

Every error response is JSON with a top-level error object:

{
  "color:#3b82f6">"error": {
    "color:#3b82f6">"type": "invalid_request_error",
    "color:#3b82f6">"code": "missing_parameter",
    "color:#3b82f6">"message": "Required parameter 'prompt' was not provided.",
    "color:#3b82f6">"param": "prompt",
    "color:#3b82f6">"requestId": "req_a1b2c3d4e5"
  }
}

Fields

Status codes

Handling errors in code

Both SDKs raise typed exception classes. Catch them by base class for broad handling, or by specific class for targeted recovery:

import {
  Cosavu,
  CosavuError,
  RateLimitError,
  AuthenticationError,
} from "@cosavu/sdk"
 
const cosavu = new Cosavu()
 
try {
  const result = await cosavu.context.optimize({ prompt: "..." })
} catch (e) {
  if (e instanceof RateLimitError) {
    console.log("Slow down. Retry after:", e.retryAfter)
  } else if (e instanceof AuthenticationError) {
    console.log("Key is bad or missing.")
  } else if (e instanceof CosavuError) {
    console.log(e.code, e.message, e.requestId)
  } else {
    throw e
  }
}

Retry strategy

The SDK automatically retries idempotent requests on 5xx and 429 responses using exponential backoff with jitter. Default: 2 retries, 250ms initial delay, capped at 8 seconds.

Configure retry behaviour at the client level:

const cosavu = new Cosavu({
  maxRetries: 5,           // default 2
  retryInitialDelay: 500,  // ms, default 250
  retryMaxDelay: 16_000,   // ms, default 8000
})

Common error codes