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

# Errors and retries

> Handle failures, rate limits, and uncertain writes without creating duplicates.

## Read an error

Errors use a JSON envelope:

```json theme={null}
{
  "error": {
    "code": "example.code",
    "message": "A description of the problem"
  }
}
```

Some errors include `details`. Log the HTTP status, error code, and `X-Request-Id` response header. Exclude API keys and customer message bodies from logs unless your own data policy requires them.

| Status | What to do |
| - | - |
| `400` | Correct the input; check required fields and parameter formats |
| `401` | Check authentication, expiry, and revocation |
| `403` | Check permissions and connection restrictions |
| `404` | Verify the resource ID belongs to the key's workspace |
| `409` | Inspect the conflict; do not blindly retry a changed request |
| `429` | Respect `Retry-After` and reduce concurrency |
| `5xx` | Retry eligible requests with exponential backoff and jitter |

## Use idempotency for supported writes

Endpoints that document `Idempotency-Key` can protect retries against duplicate writes. Generate one unique key per logical action and keep it stable across retries of that same action.

```http theme={null}
Idempotency-Key: 47d7ac31-8e9d-4db5-b6e4-0aa4eec09556
```

Retry with the same method, endpoint, query, body, and key. Do not reuse the key for a different action. A replay may include `Idempotency-Replayed: true`. Conflicting payloads or an in-progress request can return `409`.

If a write times out, it may already have completed. Use the original idempotency key when the endpoint supports it; otherwise inspect the resource before repeating the operation.

## Retry Help Center proposals

Authoring writes require an idempotency key. MCP proposal tools take it as `idempotencyKey`; HTTP requests use the header. Use 8–128 printable, non-space ASCII characters.

For a revision conflict, fetch the latest article and ask for a new review decision. Do not silently overwrite newer content. An uncertain network result should be retried only with identical arguments and the original key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.