---
title: "Errors"
description: "Status codes, the pre-stream error shape, and how to tell an incomplete stream from a failed turn."
canonical_url: "https://scholarxiv.com/developers/docs/agent-api/errors"
markdown_url: "https://scholarxiv.com/developers/docs/agent-api/errors.md"
---

> For the complete documentation index, see [llms.txt](/llms.txt).

# Errors
URL: /developers/docs/agent-api/errors
LLM index: /llms.txt
Description: Status codes, the pre-stream error shape, and how to tell an incomplete stream from a failed turn.
Related: agent-api, agent-api/streaming, papers-api/errors, papers-api/limits

# Errors

Invalid requests return 400, invalid keys 401, unavailable models or deep research 403, unknown or inaccessible chats 404, attachment quota conflicts 409, oversized model context 413, rate limits 429, and agent failures 502.

## Error shape

Pre-stream errors use:

```json
{
  "error": "The research agent could not complete this request.",
  "code": "agent_failed",
  "message": "The research agent could not complete this request.",
  "hint": "Retry the request or continue the chat with its chat_id.",
  "docs": "https://scholarxiv.com/developers/docs/agent-api"
}
```

## Status codes

| Status | Meaning | What to do |
|---|---|---|
| 400 | Invalid request body or unknown field | Check the request fields against [Quickstart](/developers/docs/agent-api/quickstart). |
| 401 | Invalid or disabled API key | Rotate the key in the [developer dashboard](/developers/dashboard/apikeys). |
| 403 | Model or deep research not on the plan | Check entitlements in [Tools and limits](/developers/docs/agent-api/tools). |
| 404 | Unknown or inaccessible chat | Confirm the `chat_id` belongs to the calling key. |
| 409 | Attachment quota conflict | Reduce `attachment_ids` or check the plan's per-chat limit. |
| 413 | Model context too large | Shorten the message or the selected context. |
| 429 | Rate limited | Respect `Retry-After` and back off — see [Rate Limits](/developers/docs/papers-api/limits). |
| 502 | Agent failure | Read history with the saved `chat_id` before retrying. |

## Streaming failures

With `stream: true`, the HTTP status is 200 once headers are sent, so failures arrive inside the stream as `error` or `abort` events. Treat the turn as unsuccessful and do not mark partial text complete. A connection that closes without a `finish` event is incomplete.

Never automatically retry a POST after losing the connection: it may already have saved a turn or run tools. See [Conversations](/developers/docs/agent-api/conversations).

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).