Error Codes - Ceramic

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

HTTP Status Codes

Code	Meaning	Cause	Retry	Action
200	Success	Request succeeded	—	Process the response
400	Invalid Request	Malformed or unparseable request body	No	Fix the request
401	Unauthorized	Invalid or missing api key	No	Check credentials
402	Payment Required	Credits exhausted	No	Add credits or upgrade your plan
403	Forbidden	Plan or account restriction	No	Check plan or account status
404	Not Found	Path does not exist	No	Verify the request path
405	Method Not Allowed	HTTP method not supported	No	Use `POST` for `/search`
408	Request Timeout	Request took too long	Yes	Retry the request
413	Payload Too Large	Request body exceeds size limit	No	Reduce request size
415	Unsupported Media	`Content-Type` is not `application/json`.	No	Set `Content-Type: application/json`
422	Unprocessable Content	Parameter is unsupported, invalid, or wrong type	No	Fix the parameter and retry
429	Too Many Requests	Rate limit exceeded	Yes	Retry after `retry_after_seconds`
500	Internal Error	Unexpected server error	Yes	Retry; contact support if it persists
502	Bad Gateway	Upstream service returned an error	Yes	Retry the request
503	Service Unavailable	Service temporarily unavailable	Yes	Retry with backoff
504	Gateway Timeout	Upstream service timed out	Yes	Retry the request

Error Response Format

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

{
  "title": "Unprocessable Content",
  "status": 422,
  "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

Documentation Index

​HTTP Status Codes

​Error Response Format

​Handling Errors

​Retry Strategy

HTTP Status Codes

Error Response Format

Handling Errors

Retry Strategy