> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ceramic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> Reference for Ceramic API error codes

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`:

```json theme={null}
{
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "Unsupported parameter: prompt",
  "requestId": "5e2ef11d-f0e5-407b-ba29-d1b851ed1d65",
  "code": "unsupported_parameter"
}
```

## Handling Errors

<Tabs sync={false}>
  <Tab title="Python">
    ```python python theme={null}
    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))
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript javascript theme={null}
    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();
    ```
  </Tab>
</Tabs>

## 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.

<Tabs sync={false}>
  <Tab title="Python">
    ```python python theme={null}
    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")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript javascript theme={null}
    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 });
    ```
  </Tab>
</Tabs>