Error Codes - Ceramic

Ceramic uses standard HTTP status error codes to indicate the success or failure of API requests.

HTTP Status Codes

Code	Meaning	Action
200	Success	Process response
401	Invalid api key	Check your `Authorization` header
429	Rate limit exceeded	Retry with backoff
500	Internal server error

Error Response Format

All errors follow the following format. For example, using an unsupported parameter like prompt instead of query:

{
  "title": "Invalid request",
  "status": 400,
  "detail": "Unsupported parameter: prompt",
  "requestId": "5e2ef11d-f0e5-407b-ba29-d1b851ed1d65",
  "code": "unsupported_parameter"
}

Handling Errors

Python
TypeScript

python

from ceramic_ai import Ceramic

client = Ceramic(api_key="YOUR_API_KEY")

try:
  client.search(query="California rental laws")
except ceramic_ai.APIStatusError as e:
  print(f"HTTP {e.status_code}")
  print("body:", e.body)
except ceramic_ai.APIConnectionError as e:
  print("Connection error:", str(e))

javascript

import Ceramic from "ceramic-ai";

const client = new Ceramic({ apiKey: "YOUR_API_KEY" });

async function main() {
  try {
    const response = await client.search({ query: "California rental laws" });
    console.log(response.requestId);
  } catch (err) {
    if (err instanceof Ceramic.APIConnectionError) {
      console.log("Connection error:", err.message);
    } else if (err instanceof Ceramic.APIError) {
      console.log(HTTP ${err.status});
      console.log("body:", err.error);
    } else {
      throw err;
    }
  }
}
main();

Retry Strategy

Both the Python and TypeScript SDKs automatically retry transient failures with a short exponential backoff. By default, the SDK retries 2 times on:

network/connection errors
408 Request Timeout
429 Rate Limit
5xx server errors

You can disable or tune retries via the client option (max_retries in Python, maxRetries in TypeScript), or per-request.

Python
TypeScript

python

from ceramic_ai import Ceramic

client = Ceramic(
    api_key="YOUR_API_KEY",
    max_retries=0,  # disable retries (default is 2)
)

# or per-request
client.with_options(max_retries=5).search(query="California rental laws")

javascript

import Ceramic from "ceramic-ai";

const client = new Ceramic({
  apiKey: "YOUR_API_KEY",
  maxRetries: 0, // disable retries (default is 2)
});

// or per-request
await client.search({ query: "California rental laws" }, { maxRetries: 5 });

Search

​HTTP Status Codes

​Error Response Format

​Handling Errors

​Retry Strategy

HTTP Status Codes

Error Response Format

Handling Errors

Retry Strategy