Error codes

cn2.ai uses structured JSON error responses with consistent error codes. All errors include an error message and a machine-readable code field.

Payment errors

Status	Description	Action
402	Payment Required — initial challenge or invalid credential	Pay the challenge amount and retry with a credential
402	Spend cap exceeded	Increase your monthly spend cap in account settings

Routing errors

Status	Code	Meaning
404	UNKNOWN_PROVIDER	The subdomain does not match any supported provider
503	NO_AVAILABLE_KEYS	No seller keys available for this provider and tier
503	NO_EU_KEYS	Your IP is in the EU but no EU-tagged keys are available for this provider
502	UPSTREAM_UNAVAILABLE	All eligible keys failed — the upstream provider may be experiencing issues

Upstream errors

When the upstream provider returns a client error (400, 403, 404, 422), cn2.ai forwards it to you unchanged — you are not charged. These are buyer errors (incorrect request format, missing fields, etc.).

When the upstream returns a server error (401, 429, 5xx), cn2.ai automatically retries on another seller's key. If all retries fail, you receive a 502. You are never charged for failed requests.

Platform errors

Status	Code	Meaning
401	—	Missing or invalid authentication token (platform API only)
500	PLATFORM_ERROR	Internal error — you are not charged. Try again.

Error response format

{
  "error": "No EU keys available for this provider",
  "code": "NO_EU_KEYS",
  "provider": "openai",
  "tier": "standard",
  "region": "eu"
}

Some errors include additional context fields like provider, tier, region, suggestion, and gdprNote.