Errors

Errors ACOG returns itself use this envelope:

{ "error": { "type": "model_not_configured", "message": "…" } }

Some types add fields, listed below. An error from your provider is passed through with its own status and body, unless ACOG maps it to one of the types below. On native routes, provider errors are always passed through unchanged. Failed responses are never cached.

Authentication and authorization

Status	type	Cause	What to do
401	unauthorized	No gateway key found, or the key is unknown, disabled, expired, or used from outside its IP allowlist	Check the key and the header it is in (Base URLs and authentication)
403	forbidden	The key lacks the gateway access scope (proxy); or, on /bedrock, the request signature does not verify	Use a key with proxy; for Bedrock, use an issued ACOG credential and a correct clock
503	service_unavailable	ACOG could not reach its key or configuration store	Retry

Governance

Status	type	Extra fields	Cause
402	budget_exhausted	scope (org, group, user), window (day, week, month), decision_id	A budget is used up. See Budgets.
429	rate_limited	Retry-After header	A rate limit is reached. See Rate limits.
403	model_not_allowed	scope (org, team, user, service-key)	A model access rule refuses the model. See Model access.
403	model_unverifiable	channel	A native-route request whose model cannot be determined, while a model access rule applies
403	dlp_blocked	category, reason, decision_id	Data loss prevention blocked the request. See Data loss prevention.
400	prompt_injection_blocked	category	Prompt injection screening blocked the request. See Prompt injection protection.

Routing and the request

Status	type	Cause	What to do
409	model_not_configured	No connection declares the model; auto with no connections; an x-acog-channel value with no matching connection; or no model in the body	Declare the model on a connection under Admin → Providers
409	connection_not_configured	A native route with no connection for that provider, or a connection missing a required setting	Create or complete the connection
409	connection_not_usable	The connection’s address, port or region is not allowed on the hosted service	Edit the connection (Connecting providers)
400	invalid_request_error	The body is not valid for the endpoint, a referenced image could not be fetched, or a native path contains . or .. segments	Fix the request
413	request_too_large	The body is over 64 MiB	Send less, or reference large files by URL
413	context_window_exceeded	The prompt is larger than the model’s context window. Extra fields: model, context_window, estimated_tokens.	Shorten the prompt or use a model with a larger window
422	translation_unsupported	A field cannot be translated faithfully to the serving model’s API	Remove the field, or call a model that speaks the same API
422	embeddings_unsupported_shape	No connection that declares the model can serve embeddings	Declare the model on an OpenAI, Azure OpenAI or compatible connection

Your provider

Status	type	Extra fields	Cause	What to do
422	model_access_required	provider_status, provider_detail	Your provider account cannot use the model (Bedrock model access, Vertex Model Garden, Azure deployment)	Enable the model in your provider account; the message says how
422	upstream_auth_failed	provider_status, provider_detail	Your provider rejected the connection’s stored key	Update the key under Admin → Providers
502	upstream_auth_error		ACOG could not obtain a credential for the provider, for example a keyless exchange was refused	See the provider’s troubleshooting section (Keyless connections)
500	credentials_error		A stored credential could not be used	Contact your administrator; re-enter the connection’s credentials
502	upstream_error		A network or protocol failure reaching the provider	Retry
503	upstream_unavailable	Retry-After: 5	The provider’s platform is failing repeatedly and ACOG is pausing requests to it	Retry after the delay

Batches

Status	type	Cause
404	batch_not_found	No such batch job for your organization
502	batch_failed	The provider’s batch job failed. Extra fields: id, status.
502	batch_poll_failed, batch_connection_unavailable	ACOG could not check the job, or the job’s connection no longer exists

Hosted service: errors from the edge

These apply only to the console’s address, acog.tessarac.com/gateway, which goes through the edge network in front of the console. There, a request that sends nothing back for 60 seconds is closed with 504, and some 403, 404 and 5xx responses arrive as an HTML page from the edge rather than the JSON envelope above. gateway.acog.tessarac.com has no edge in front of it; use it, and see Base URLs.