Skip to main content
Where a request fails determines how the error comes back:

Authentication errors

The Box API gateway handles authentication, so these errors are the same as for other Box API calls.

HTTP+JSON errors

error.code matches the HTTP status, and error.status is a gRPC-style status string. Handle errors based on details[].reason, which is a stable, machine-readable identifier, rather than message.

JSON-RPC errors

JSON-RPC errors always return HTTP 200, with the failure in the response body. Check the body for an error object instead of checking the status code.

Failed tasks

If the agent fails after it starts running, the request still succeeds and returns a task in TASK_STATE_FAILED. The task’s status message contains a text part with a readable message, and a data part with the media type application/vnd.box.execution-error+json:
You can’t resume a failed task with its taskId. When retryable is true, send a new message on the same contextId. The agent continues from the point of failure where it can, as a new task.

Rejected tasks

When Box refuses a valid request before the agent runs, it returns a task in TASK_STATE_REJECTED. The status message has the same reason, retryable, and message fields as a failed task.

Troubleshooting

Last modified on November 17, 2026