Errors and troubleshooting
Choose a recovery action based on the interface and operation that failed.
Read the response before retrying
Engine errors are JSON {"error": "..."} with a human message and no machine code. Every response carries X-Request-ID.
| Status and meaning | What to do |
|---|---|
400 The body cannot be read, for example invalid json. | Fix the request. |
| 401 No API key, an unknown one, or an expired session token. | Send a valid credential. |
| 402 A charged workflow call found too few credits, for example an instance or case start, a model deploy, a decision evaluation or a task completion. | Wait for the next daily grant or buy a pack. Agent memory never answers 402. |
| 403 The firewall banned this IP after three rate-limit strikes. The body is empty. | Wait: the ban lasts 2 hours and doubles on each repeat. |
| 404 An unknown route or record. On job complete or fail: the job is gone, already completed, failed to zero retries or cancelled. | Read the instance to reconcile. |
| 422 Well formed but impossible: an unknown process, decision or case, or a model that does not parse. | Deploy the model or fix it. |
| 429 More than 300 requests in a sliding 60 seconds from one IP address. Plain text, no retry header. | Back off about 60 seconds before retrying. |
| 5xx A server error. | Keep the X-Request-ID; reconcile side effects before retrying. |
An HTTP success can contain a tool failure
For MCP, inspect the JSON-RPC result and the tool envelope. Parse the JSON text before checking ok and outcome. A denial on agent memory, such as capability-denied, arrives as an outcome inside an HTTP 200, never as a 403, so do not treat HTTP 200 as proof that a store or grant succeeded.
Collect a reproducible report
- Record the endpoint or tool name and timestamp.
- Include a redacted request and response, plus the request or instance identifier.
- State the expected result and the smallest reproduction.
- Exclude tokens, API keys and customer data from the report.
Machine-readable contracts: MCP tools JSON · OpenAPI JSON. See the contract notes for older examples.
CONTINUE READINGCredits, limits and usage →