> ## Documentation Index
> Fetch the complete documentation index at: https://developer.box.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Handle errors

> Handle Box Agents API authentication errors, HTTP+JSON and JSON-RPC errors, failed and rejected tasks, and common problems.

Where a request fails determines how the error comes back:

| Where it fails | What you get |
| - | - |
| Authentication, before the request reaches the API | A flat JSON error with HTTP `400`, `401`, or `404` |
| A malformed or invalid HTTP+JSON request | A structured error envelope |
| A malformed or invalid JSON-RPC request | A JSON-RPC error object with HTTP `200` |
| The agent ran and failed | A task in `TASK_STATE_FAILED` |
| A valid request refused before the agent ran | A task in `TASK_STATE_REJECTED` |

## Authentication errors

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

```json theme={null}
{ "error": "Malformed auth header" }
```

| Condition | HTTP | Message |
| - | - | - |
| The token is missing, or the `Authorization` header is malformed | `400` | `Malformed auth header` |
| The token is expired or otherwise invalid | `401` | `The access token provided is invalid` |
| An admin hasn't enabled **AI via API/MCP/A2A/CLI** for the enterprise | `404` | `authorization failed` |

## HTTP+JSON errors

```json theme={null}
{
  "error": {
    "code": 404,
    "status": "NOT_FOUND",
    "message": "Task does-not-exist not found",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "TASK_NOT_FOUND",
        "domain": "a2a-protocol.org"
      }
    ]
  }
}
```

`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`.

| A2A error | HTTP | `status` | `reason` |
| - | - | - | - |
| `TaskNotFoundError` | `404` | `NOT_FOUND` | `TASK_NOT_FOUND` |
| `PushNotificationNotSupportedError` | `400` | `FAILED_PRECONDITION` | `PUSH_NOTIFICATION_NOT_SUPPORTED` |
| `UnsupportedOperationError` | `400` | `FAILED_PRECONDITION` | `UNSUPPORTED_OPERATION` |
| `ContentTypeNotSupportedError` | `400` | `INVALID_ARGUMENT` | `CONTENT_TYPE_NOT_SUPPORTED` |
| `ExtendedAgentCardNotConfiguredError` | `400` | `FAILED_PRECONDITION` | `EXTENDED_AGENT_CARD_NOT_CONFIGURED` |
| `ExtensionSupportRequiredError` | `400` | `FAILED_PRECONDITION` | `EXTENSION_SUPPORT_REQUIRED` |
| `VersionNotSupportedError` | `400` | `FAILED_PRECONDITION` | `VERSION_NOT_SUPPORTED` |
| `InvalidParamsError` | `400` | `INVALID_ARGUMENT` | `INVALID_PARAMS` |
| `InvalidRequestError` | `400` | `INVALID_ARGUMENT` | `INVALID_REQUEST` |
| `MethodNotFoundError` | `404` | `NOT_FOUND` | `METHOD_NOT_FOUND` |
| `InternalError` | `500` | `INTERNAL` | `INTERNAL_ERROR` |
| `ConflictError` | `409` | `ABORTED` | `CONFLICT` |

## 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.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "1",
  "error": { "code": -32004, "message": "This operation is not supported" }
}
```

| Code | Error |
| - | - |
| `-32700` | `JSONParseError` |
| `-32600` | `InvalidRequestError` |
| `-32601` | `MethodNotFoundError` |
| `-32602` | `InvalidParamsError` |
| `-32603` | `InternalError` |
| `-32001` | `TaskNotFoundError` |
| `-32003` | `PushNotificationNotSupportedError` |
| `-32004` | `UnsupportedOperationError` |
| `-32005` | `ContentTypeNotSupportedError` |
| `-32006` | `InvalidAgentResponseError` |
| `-32007` | `ExtendedAgentCardNotConfiguredError` |
| `-32008` | `ExtensionSupportRequiredError` |
| `-32009` | `VersionNotSupportedError` |
| `-32012` | `ConflictError` |

## 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`:

```json theme={null}
{
  "task": {
    "id": "3706d316-0832-421d-9ce6-5aa645598ce9",
    "contextId": "410109491801",
    "status": {
      "state": "TASK_STATE_FAILED",
      "timestamp": "2022-01-01T00:00:00Z",
      "message": {
        "messageId": "c3f1a2b4-...",
        "role": "ROLE_AGENT",
        "parts": [
          { "text": "Agent execution exceeded the maximum allowed time." },
          {
            "data": {
              "reason": "execution_timeout",
              "retryable": true,
              "message": "Agent execution exceeded the maximum allowed time."
            },
            "mediaType": "application/vnd.box.execution-error+json"
          }
        ]
      }
    }
  }
}
```

| Field | Meaning |
| - | - |
| `reason` | Why the run failed |
| `retryable` | Whether sending the request again might succeed |
| `message` | The readable message, which matches the text part |

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.

| Condition | What to do |
| - | - |
| The user or enterprise has reached its AI Units or daily limit | Retry later, or contact your Box admin. |
| The caller can't access content that the request references | Check the item IDs and the caller's access to them. |

## Troubleshooting

| Symptom | Likely cause | Fix |
| - | - | - |
| `400` with `Malformed auth header` | The token is missing, or the `Authorization` header is formatted incorrectly | Send the header as `Authorization: Bearer ACCESS_TOKEN`. |
| `401` with `The access token provided is invalid` | The token expired, or a developer token is older than one hour | Refresh the token. |
| `404` with `authorization failed` | An admin hasn't enabled **AI via API/MCP/A2A/CLI** for the enterprise | Ask your Box admin to enable it. |
| `403` when the agent reads content | The app is missing `root_readonly` or `root_readwrite`, or the caller can't access the item | Enable the scope and reauthorize the app, or check the caller's collaboration on the item. |
| `400 INVALID_PARAMS` with "non actionable request" | The message contains only `data` parts | Add a text part with the prompt. |
| `400 INVALID_PARAMS` that names `data.id` or `data.type` | A content reference is missing a required key | Include both `id` and `type`. |
| `-32009` or `VERSION_NOT_SUPPORTED` | A JSON-RPC request is missing the version header | Add `A2A-Version: 1.0`. |
| `400 INVALID_PARAMS` with "is in terminal state" | The request reuses a finished `taskId` | Send only the `contextId` so Box creates a new task. |
| `400 FAILED_PRECONDITION` with `PUSH_NOTIFICATION_NOT_SUPPORTED` | The request uses push notifications, which aren't supported | Use `message:stream`, or poll `GET /tasks/{taskId}`. |
| `404 TASK_NOT_FOUND` for a task you just created | Box couldn't find the stored task | Use the task returned in the `message:send` response, or the `artifactUpdate` events from `message:stream`. |
| `409 CONFLICT` with "Cannot create a new task: prior task … is still in non-terminal state" | The session already has a task that's working | Wait for the task to finish, or start a new session. |

**RELATED GUIDES**
