Errors
Handle AI gateway failures predictably.
Applications should treat ModelSpend errors as structured signals: authentication, validation, policy, provider and timeout failures need different recovery paths.
Standard shape
{
"error": "Human-readable message",
"code": "VALIDATION_ERROR",
"details": {}
}
"error": "Human-readable message",
"code": "VALIDATION_ERROR",
"details": {}
}
Common codes
UNAUTHENTICATED
Missing, invalid or revoked API key. Check key storage and rotation.
VALIDATION_ERROR
Request payload did not match the expected API shape.
POLICY_DENIED
The request was blocked by tenant policy, budget or provider rules.
PROVIDER_UPSTREAM_ERROR
The selected upstream provider returned an error or unavailable response.
BUDGET_EXCEEDED
The request would exceed a configured spend boundary.
TIMEOUT
The route or provider did not complete within the configured time limit.
Recovery guidance
Retry only when the failure is transient. Do not blindly retry validation, authentication, policy or budget errors; those require configuration or request changes.