# Errors and Status Codes

The IntelCenter API uses standard HTTP status codes. The exact response schema for each operation is in the [API Reference](/api).

| Status | Meaning |
|---|---|
| `200 OK` | Request succeeded |
| `204 No Content` | Conversation deletion succeeded |
| `400 Bad Request` | Input is invalid |
| `401 Unauthorized` | Authentication is missing or invalid |
| `403 Forbidden` | The key lacks a required permission |
| `404 Not Found` | The route or requested resource is unavailable in this context |
| `429 Too Many Requests` | A rate or usage control blocked the request |
| `500 Internal Server Error` | An unexpected service error occurred |

## Common Shape

```json
{
  "error": "error_code",
  "message": "Human-readable description"
}
```

Some operations use a problem-details response or add documented context fields.

Public error responses omit internal diagnostic traces, deployment and build identifiers, stack details, and infrastructure request identifiers. These implementation-only values are not part of the public contract.

## Authentication and Permission Errors

For `401`, confirm the Bearer header and intended environment. For `403`, confirm the API key's dataset and capability assignments.

## Not Found and Unavailable

A not-found or unavailable response may intentionally avoid confirming whether content exists outside the API key's authorization scope.

An unavailable Domain GenAI conversation returns:

```json
{
  "error": "conversation_unavailable",
  "message": "This conversation is unavailable. Omit conversation_id to start a new conversation."
}
```

This response can mean the identifier is expired, deleted, belongs to another credential or dataset, or is otherwise unavailable.

## Rate and Usage Errors

For `429`:

- Honor `Retry-After` when present.
- Apply exponential backoff with jitter.
- Do not automatically replay Domain GenAI as an idempotent request.
- Reduce request frequency or contact IntelCenter if the assigned limits are insufficient.

## Service Errors

Retry safe retrieval requests after a brief delay. Before retrying a Domain GenAI request, determine whether the prior call may have succeeded to avoid creating a duplicate turn or charge.

## MCP

MCP tool errors use the same authentication, authorization, rate, and privacy rules as REST. A client may present the structured failure in its own interface.

## Support

If an error persists, contact `support@intelcenter.com` with the timestamp, request path, status code, and any non-sensitive request identifier. Never include an API key.