Error codes

Kinds of failure on a recorded call

Every failed call is recorded with the provider's own error code, and grouped into one kind, so the same failure reads the same across providers. Group by error_class over the API to count them.

`error_class`	Shown as	Whose	What it means
`ERROR_CLASS_RATE_LIMITED`	Rate limit exceeded	Provider	Over a rate or quota. Retrying after the wait usually works.
`ERROR_CLASS_TIMEOUT`	Request timed out	Provider	No answer in time. Retrying may work.
`ERROR_CLASS_UNAVAILABLE`	Service unavailable	Provider	The provider or tool was down, overloaded or unreachable.
`ERROR_CLASS_SAFETY_BLOCKED`	Blocked by content filter	Provider	A safety filter stopped the prompt or the answer.
`ERROR_CLASS_INVALID_REQUEST`	Invalid request	Yours	The provider rejected the request as sent. It fails until the request changes.
`ERROR_CLASS_NOT_FOUND`	Resource not found	Yours	The model named does not exist, or this account cannot use it.
`ERROR_CLASS_PERMISSION_DENIED`	Access denied	Yours	The provider credential was missing, wrong or not allowed.
`ERROR_CLASS_CONTEXT_OVERFLOW`	Context window exceeded	Yours	The request held more tokens than the model accepts.
`ERROR_CLASS_BILLING`	Billing limit reached	Yours	The provider account cannot pay: a spend limit, an empty balance or billing off.
`ERROR_CLASS_TOOL_ERROR`	Tool execution failed	Yours	The tool ran and failed in its own code.
`ERROR_CLASS_CANCELLED`	Request cancelled	Unknown	The caller stopped waiting. Nothing was wrong with the call.
`ERROR_CLASS_UNKNOWN`	Unknown error	Unknown	A code not yet mapped. The provider's code is shown beside it.

A call that did not fail has the class ERROR_CLASS_UNSPECIFIED. Grouped by error_class, a row's errorClassOwner says whose it is: ours for the ones marked Yours above, meaning your own request was at fault, provider, or unknown.

Two statuses are not failures of the call itself: DENIED, stopped by your budget before it was sent and never billed, and TRUNCATED, stopped at a token limit or deadline after doing part of the work.

Errors from the API

Status	Why	What to do
`400`	A parameter is unknown or badly written: a missing window, a time zone, dimension, filter, read mask or page token that is not valid.	Check the `reason` and `field`, below.
`401`	The key or secret is missing, unknown or revoked.	Send both headers. Create a new key if this one was revoked.
`403`	A key without Read was used, or the path names another organisation.	Use a read key belonging to the organisation in the path.
`429`	Over your organisation's rate limit.	Wait the seconds in `Retry-After`, then retry.

Every refusal's body carries a reason your code can check, the field at fault where one is, and the requestId to quote when you contact us:

`reason`	`field`	What to change
`UNKNOWN_PARAMETER`	The parameter	Remove it, or check its spelling against the method's page.
`INVALID_PARAMETER`	The parameter	Send it in the type the method's page gives, once. A time is RFC 3339, such as `2026-10-01T00:00:00Z`, and `orderBy` takes only `occurred_at desc`.
`MISSING_WINDOW`	`startTime`	Send both `startTime` and `endTime`.
`INVALID_WINDOW`	`startTime` or `endTime`	Send both, with the end after the start.
`INVALID_TIME_ZONE`	`timeZone`	Send an IANA name, such as `Africa/Nairobi`.
`UNKNOWN_DIMENSION`	`groupBy`	Use a dimension the message lists.
`UNKNOWN_FILTER_FIELD`	`filter`	Filter on a field the message lists.
`INVALID_FILTER_VALUE`	`filter`	Use a value the message lists for that field.
`INVALID_FILTER`	`filter`	Write terms of `field = value` joined by `AND`.
`UNKNOWN_READ_MASK_FIELD`	`readMask`	Name figures the message lists.
`INVALID_PAGE_TOKEN`	`pageToken`	Pass back the `nextPageToken` exactly as it came.

Any other refusal's reason is its code in capitals, such as PERMISSION_DENIED or RESOURCE_EXHAUSTED.

Errors from the recorders

Error	When	What to do
Settings error at startup	An `AP_*` setting is missing or malformed, for example an agent outside the key's organisation.	Fix the setting. The message names it.
`SpendDenied`	A budget stopped the call. Recognise it with `agentpulse.denied(err)`, `denied(err)` or `recorder.Denied(err)`.	Tell your user in your own words.
`403` from the LiteLLM proxy	A budget stopped the call. Marked not to be retried.	As above.

Nothing else the recorder does raises into your code. Problems sending records show in its stats instead.