Error Handling

All errors from the AI Stats Gateway should be returned in a consistent JSON structure:

{
	"generation_id": "G-abc123",
	"status_code": 401,
	"error": "validation_error",
	"error_type": "user",
	"description": "Input validation failed"
}

Every response includes:

generation_id: a stable identifier you can share with support for faster investigation.
status_code: mirrors the HTTP status to make retries decisions easier.
error: a machine-readable error code (for example validation_error).
error_type: high-level classification (user or system).
description: a human-friendly explanation safe to display to end users.
details (optional): structured validation errors when error is validation_error.

Common error codes

Type	HTTP Status	Description
`authentication_error`	`401`	Missing or invalid API key.
`authorization_error`	`403`	Key lacks permission to access this resource.
`not_found_error`	`404`	The endpoint or resource could not be found.
`rate_limit_error`	`429`	Too many requests. Retry after the specified delay.
`validation_error`	`400`	Invalid parameters or request body.
`provider_error`	`502`	Upstream model provider failed to respond correctly.
`server_error`	`500`	Unexpected issue within the Gateway.

Example:

if (error.error === "rate_limit_error") {
	await sleep(retryAfterMs);
	return retryRequest();
}

Check the Gateway status page for ongoing incidents.
Review your request payloads — strict JSON validation is enforced.
Use the generation_id (from the response body) when contacting support as this helps us identify your request.

How to authenticate with your API key securely.

Test connectivity and verify Gateway uptime.