---
title: "Errors"
description: "Status codes, the pre-stream error shape, run conflicts, idempotency errors, 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, run conflicts, idempotency errors, and how to tell an incomplete stream from a failed turn.
Related: agent-api, agent-api/runs, 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 and runs 404, run and attachment conflicts 409, oversized model context 413, a reused Idempotency-Key 422, 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"
}
```

Some errors add fields: `run_in_progress` includes the `run_id` of the turn that is running.

## Status codes

| Status | Codes                                                                                    | What to do                                                                                  |
| ------ | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| 400    | `invalid_request`, `invalid_json`, `invalid_idempotency_key`, `attachment_not_available` | Check the request against [Quickstart](/developers/docs/agent-api/quickstart).              |
| 401    |                                                                                          | Rotate the key in the [developer dashboard](/developers/dashboard/apikeys).                 |
| 403    | `model_unavailable`, `deep_research_unavailable`                                         | Check entitlements in [Tools and controls](/developers/docs/agent-api/tools).               |
| 404    | `chat_not_found`, `run_not_found`                                                        | Confirm the id belongs to the calling key. Runs are kept for 24 hours.                      |
| 409    | `run_in_progress`                                                                        | A turn is already running on this chat. Wait for it, stream it, or cancel it.               |
| 409    | `idempotency_in_progress`                                                                | The first request with this key is still starting. Retry in a few seconds.                  |
| 409    | `chat_attachment_limit_exceeded`, `chat_changed`                                         | Reduce `attachment_ids` or check the plan's per-chat limit.                                 |
| 413    | `context_too_long`                                                                       | Shorten the message or the selected context.                                                |
| 422    | `idempotency_key_reused`                                                                 | The key was used with a different body. Use a new key for a new request.                    |
| 429    |                                                                                          | Respect `Retry-After` and back off — see [Rate Limits](/developers/docs/papers-api/limits). |
| 502    | `agent_failed`, `agent_stream_failed`                                                    | Read the run or the conversation before retrying, or retry with the same `Idempotency-Key`. |

## 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 a missing `finish` event as an incomplete view of the turn: the research still finishes on the server. Resume the stream from the last event id, or read the run — see [Runs](/developers/docs/agent-api/runs).

## Failed runs

A run read from `GET /api/v1/runs/{run_id}` with `status: "failed"` has an `error`. `run_interrupted` means the server process running the turn stopped before it finished; whatever was saved is in the conversation, and the conversation is free for a new message.

## Retrying

Never automatically resend a POST that has no `Idempotency-Key` after losing the connection: the turn may already be running or finished. Send keys on every POST and retries become safe. See [Runs](/developers/docs/agent-api/runs#retry-safely-with-idempotency-key).

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