# Errors and retries

JSON success envelopes use {request_id,status,data,meta}. Handled API errors use {request_id,status:"error",data:null,meta:{},error:{code,message,retryable}}. Keep request_id when asking for support. File downloads return a stream instead of a JSON envelope.

- **401:** replace an invalid key or reconnect a revoked OAuth app.
- **403:** request the required scope or lower the task cap to the key limit.
- **409:** read the task before retrying. Use a new idempotency key when the request changes.
- **413:** request fewer result fields or rows; request bodies have a 1 MiB maximum.
- **422:** correct the path, query or JSON body.
- **429:** wait for Retry-After, then retry with backoff.
- **5xx:** retry only when error.retryable is true or the operation is safe to repeat. Do not repeat a tool run blindly.

Task creation and find accept idempotency keys. Reuse the same key only for the same inputs. Reply, cancel, share and run_tool do not have request idempotency keys.

[All documentation](https://leadsagent.io/documentation/quickstart)
[OpenAPI](https://leadsagent.io/documentation/openapi.json)