Errors and troubleshooting
Diagnose connection, input and recovery failures before retrying.
Read the error response
HTTP tool failures normally return an error object with code, message and traceId; validation errors can include details. Inspect the HTTP status as well. Proxies and body-size limits may return a different body, so tolerate non-JSON responses in production clients. Record the tool name, time, job ID and traceId for diagnosis, with credentials and private media URLs removed.
{
"error": {
"code": "INVALID_JSON",
"message": "Malformed JSON",
"traceId": "<diagnostic-id>"
}
}Common failures
| Signal | Resolution |
|---|---|
| 401 · UNAUTHORIZED | Check the runtime workspace key and Bearer header, not the website login or provider key. |
| 403 · FORBIDDEN | Check read/write/admin scope, ownership and browser origin rules. |
| 404 · NOT_FOUND | Check the tool name, installed version and account ownership of the record. |
| 400 · INVALID_JSON | Send valid JSON with the correct content type. |
| UPLOAD_EXPIRED / UPLOAD_MISMATCH | Create a fresh intent if expired; otherwise recheck byte count and SHA-256 of the exact file. |
| REVISION_CONFLICT | Read the latest snapshot, then reapply the edit without overwriting newer work. |
| 413 | Reduce the body. Use the binary upload route for assets, not a base64 tool argument. |
Retry rules
Retry read operations with a bounded delay for transient network failures. For a mutation with an uncertain response, recover the stored job or request first. Reusing an idempotency key is appropriate only for the same operation and payload. A changed brief, model or reference requires fresh preparation. Never interpret an interrupted connection as cancellation of provider work.