Errors

Response shape

Every error returns application/json carrying the same envelope:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "max_characters_per_result must be between 100 and 1000000, got 50"
  }
}

Branch on code. It is a stable, all-caps name drawn from a closed set, and the codes each endpoint can return are listed below. message is a human-readable summary written for a person reading a log — it may be reworded at any time, so don’t match on it.

/chat/completions is the exception. It returns the OpenAI-shaped envelope (type, param, lower-case code) so that unmodified OpenAI SDKs work against it. See Chat Completions reference.

When stream: true on /answer and a failure happens after streaming has already started, it’s delivered as a single terminal SSE frame under HTTP 200, with no trailing data: [DONE], rather than as a top-level error status. That frame carries the same code as the buffered response:

data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"error"}],"error":{"code":"UNAUTHENTICATED","message":"Invalid, expired, or revoked API key"}}

Errors caught before streaming starts — an invalid API key, an unrecognized scope, an oversized query — still return their normal status code and JSON body, whether or not stream is set.

Status codes

Status	`error.code`	Applies to	Description
400	`INVALID_REQUEST`	`search`, `answer`	Malformed body, or a parameter outside its accepted range.
401	`UNAUTHENTICATED`	`search`, `answer`	Invalid or missing API key.
402	`INSUFFICIENT_CREDITS`	`search`, `answer`	Insufficient account balance.
404	`NOT_FOUND`	`search`, `answer`	Endpoint not found, or a scope that matches nothing.
405	`METHOD_NOT_ALLOWED`	`search`, `answer`	Wrong HTTP method for this endpoint.
408	`DEADLINE_EXCEEDED`	`answer` only	The answer did not complete in time.
413	`REQUEST_TOO_LARGE`	`search`, `answer`	Request body is over the size limit.
415	`UNSUPPORTED_MEDIA_TYPE`	`answer` only	`Content-Type` is not `application/json`.
429	`RATE_LIMITED`	`search`, `answer`	Rate limit exceeded. Wait before retrying.
500	`INTERNAL`	`search`, `answer`	Internal server error.
502	`INTERNAL`	`answer` only	Upstream provider failure.
503	`UNAVAILABLE`	`answer` only	A backend dependency is unavailable. Safe to retry.

413 and 429 are worth retrying only after changing the request or waiting. 503 is the one to retry unchanged. The same envelope and the same codes are used by Fetch and Monitor, so one error handler covers every endpoint except /chat/completions.

Codes are per endpoint, and an endpoint may define one for a condition no other has — /agent/runs answers a rejected output_schema with INVALID_OUTPUT_SCHEMA rather than a second flavour of INVALID_REQUEST. Treat an unrecognized code as a generic failure for its status class rather than rejecting the response.

The 8 KiB limit on Answer

/answer’s query and system_prompt fields share an 8 KiB (8,192-byte) UTF-8 limit, since both are forwarded verbatim into the upstream prompt. Exceeding it returns a 400:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "query exceeds maximum length of 8192 bytes"
  }
}

This limit is specific to /answer. An oversized query on /search does not raise an error — it simply isn’t likely to match anything, and the response comes back as a normal 200 with an empty documents array.

Scopes

Both endpoints accept scope: web (beta), news, wikipedia, people, companies, or financial-reports, defaulting to web when omitted. An unrecognized value returns 404 with code NOT_FOUND and the message Scope not found.

Next steps

Search — Full request and response specification
Answer — Full request and response specification
Data Concepts — What each scope contains

Overview

Endpoints

Agent

Monitor

Specification

Errors

Response shape

Status codes

The 8 KiB limit on Answer

Scopes

Next steps

​Response shape

​Status codes

​The 8 KiB limit on Answer

​Scopes

​Next steps

Response shape

Status codes

The 8 KiB limit on Answer

Scopes

Next steps