API reference
Errors and retries
Read the HTTP status and error envelope before deciding what to do next.
{
"ok": false,
"api_version": "1",
"error": "forbidden",
"message": "This key does not grant this operation."
}- 400
- Check request fields and the idempotency key.
- 401
- Use a valid, unexpired API key.
- 403
- The key does not grant this operation.
- 404
- The item is absent or no longer assigned to you.
- 409
- The state changed, or a request ID was reused with different input. Read the current state first.
- 413
- The JSON body is too large. Upload file bytes directly to storage.
- 422
- Correct the invalid fields reported in the response.
- 429
- Follow Retry-After before making another request.
- 500 / 502 / 503
- The request could not be completed. Check service availability before retrying.
Retrying a write
Supply an Idempotency-Key header for every write, or request_id for MCP. Use 8 to 48 letters, digits, underscores or hyphens. Retry the same operation and input with the same value; a replayed response includes replayed: true. Use a new value for a new action.
Upload initiation creates a fresh URL and must not be retried automatically. Before repeating a delivery or changing job progress after an uncertain response, read its current state.
Support and MCP errors
Keep the X-Request-Id response header when reporting an HTTP failure. An MCP tool failure has isError: true and the error envelope in its text content. Successful calls return both text and structured content.