Report API spend limit errors by scope (#62329)

## Why

Generic quota errors hide whether the project or organization spend limit
blocked a request. Reporting the scope tells users which limit to check.

## What changed

Recognize API key, project, and organization spend limit errors across
HTTP, SSE, and WebSocket responses. Show a message that names the scope and
treat the error as non-retryable, even when the provider sends
`Retry-After`. Apply the existing usage-limit handling to goals and
compaction.

Expose distinct `CodexErrorInfo` values in the app-server protocol and
generated bindings so clients can identify the limit in live errors and
failed turn history.

## Testing

Extend the transport tests to cover all three scopes and verify that they
stop retries. Extend the app-server test to check that the error survives
`thread/read` and that a subsequent turn can succeed in the same thread.

GitOrigin-RevId: 03341f7a78daa7540e7baa519f1a29ec07e34509
This commit is contained in:
Alex Chang
2026-11-18 18:11:54 +00:00
committed by copyberry
parent 0ba514837d
commit cc7a62e19c
47 changed files with 291 additions and 60 deletions
+4 -2
View File
@@ -34,6 +34,7 @@ pub fn map_api_error(err: ApiError) -> CodexErr {
| ApiError::ContentFilter
| ApiError::ResponseIncomplete(_)
| ApiError::ContextWindowExceeded
| ApiError::SpendLimitExceeded(_)
| ApiError::QuotaExceeded
| ApiError::UsageNotIncluded
| ApiError::SessionBudgetExceeded
@@ -60,6 +61,9 @@ pub fn map_api_error(err: ApiError) -> CodexErr {
fn map_api_error_details(err: ApiError) -> CodexErr {
match err {
ApiError::ContextWindowExceeded => CodexErr::ContextWindowExceeded,
ApiError::SpendLimitExceeded(scope) => {
CodexErrorDetails::APISpendLimitExceeded(scope).into()
}
ApiError::QuotaExceeded => CodexErr::QuotaExceeded,
ApiError::UsageNotIncluded => CodexErr::UsageNotIncluded,
ApiError::SessionBudgetExceeded => CodexErr::SessionBudgetExceeded,
@@ -263,8 +267,6 @@ fn map_api_error_details(err: ApiError) -> CodexErr {
Some(
"insufficient_quota"
| "credit_balance_exhausted"
| "organization_spend_limit_exceeded"
| "project_spend_limit_exceeded"
| "organization_usage_limit_exceeded"
)
)
+45 -16
View File
@@ -584,23 +584,52 @@ fn map_api_error_keeps_other_400_errors_generic() {
#[test]
fn map_api_error_distinguishes_http_quota_errors_from_rate_limits() {
for error in [
serde_json::json!({"type": "insufficient_quota"}),
serde_json::json!({"code": "insufficient_quota"}),
serde_json::json!({"code": "credit_balance_exhausted"}),
serde_json::json!({"code": "organization_spend_limit_exceeded"}),
serde_json::json!({"code": "project_spend_limit_exceeded"}),
serde_json::json!({"code": "organization_usage_limit_exceeded"}),
serde_json::json!({"type": "rate_limit_error", "code": "rate_limit_exceeded"}),
serde_json::json!({"type": "rate_limit_error", "code": "slow_down"}),
use CodexErrorInfo::ApiKeySpendLimitExceeded;
use CodexErrorInfo::OrganizationSpendLimitExceeded;
use CodexErrorInfo::ProjectSpendLimitExceeded;
use CodexErrorInfo::UsageLimitExceeded;
let rate_limit = CodexErrorInfo::ResponseTooManyFailedAttempts {
http_status_code: Some(429),
};
for (error, expected) in [
(
serde_json::json!({"type": "insufficient_quota"}),
UsageLimitExceeded,
),
(
serde_json::json!({"code": "insufficient_quota"}),
UsageLimitExceeded,
),
(
serde_json::json!({"code": "credit_balance_exhausted"}),
UsageLimitExceeded,
),
(
serde_json::json!({"type": "insufficient_quota", "code": "api_key_spend_limit_exceeded"}),
ApiKeySpendLimitExceeded,
),
(
serde_json::json!({"type": "insufficient_quota", "code": "organization_spend_limit_exceeded"}),
OrganizationSpendLimitExceeded,
),
(
serde_json::json!({"type": "insufficient_quota", "code": "project_spend_limit_exceeded"}),
ProjectSpendLimitExceeded,
),
(
serde_json::json!({"code": "organization_usage_limit_exceeded"}),
UsageLimitExceeded,
),
(
serde_json::json!({"type": "rate_limit_error", "code": "rate_limit_exceeded"}),
rate_limit.clone(),
),
(
serde_json::json!({"type": "rate_limit_error", "code": "slow_down"}),
rate_limit,
),
] {
let expected = if error["type"] == "rate_limit_error" {
CodexErrorInfo::ResponseTooManyFailedAttempts {
http_status_code: Some(429),
}
} else {
CodexErrorInfo::UsageLimitExceeded
};
let err = map_api_error(ApiError::Transport(TransportError::Http {
retry_after: None,
status: http::StatusCode::TOO_MANY_REQUESTS,
+13
View File
@@ -2,6 +2,7 @@ use crate::rate_limits::RateLimitError;
use codex_client::TransportError;
use codex_http_client::RetryAfter;
use codex_protocol::error::ResponseIncompleteError;
use codex_protocol::error::SpendLimitScope;
use codex_protocol::protocol::MisalignmentErrorDetails;
use http::StatusCode;
use serde_json::Value;
@@ -25,6 +26,8 @@ pub enum ApiError {
ContextWindowExceeded,
#[error("quota exceeded")]
QuotaExceeded,
#[error("spend limit exceeded")]
SpendLimitExceeded(SpendLimitScope),
#[error("usage not included")]
UsageNotIncluded,
#[error("session budget exceeded")]
@@ -100,6 +103,16 @@ pub(crate) fn parse_terminal_provider_error(
.and_then(Value::as_str)
.filter(|message| !message.trim().is_empty());
match (code, status) {
("api_key_spend_limit_exceeded", None | Some(StatusCode::TOO_MANY_REQUESTS)) => {
Some(ApiError::SpendLimitExceeded(SpendLimitScope::ApiKey))
}
("project_spend_limit_exceeded", None | Some(StatusCode::TOO_MANY_REQUESTS)) => {
Some(ApiError::SpendLimitExceeded(SpendLimitScope::Project))
}
("organization_spend_limit_exceeded", None | Some(StatusCode::TOO_MANY_REQUESTS)) => {
Some(ApiError::SpendLimitExceeded(SpendLimitScope::Organization))
}
("inference_hook_denied", None | Some(StatusCode::FORBIDDEN)) => {
Some(ApiError::InferenceHookDenied {
message: message
+1
View File
@@ -710,6 +710,7 @@ async fn process_sse_with_treatment(
| ApiError::ContextWindowExceeded
| ApiError::InvalidRequest { .. }
| ApiError::SessionBudgetExceeded
| ApiError::SpendLimitExceeded(_)
| ApiError::InferenceHookDenied { .. }
| ApiError::AccessProgramNotEnabled { .. }
| ApiError::ContentPolicyViolation { .. }
@@ -45,12 +45,7 @@ pub(super) fn parse_failed_response(response: Option<Value>) -> ApiError {
};
match error.code.as_deref() {
Some(
"insufficient_quota"
| "credit_balance_exhausted"
| "organization_spend_limit_exceeded"
| "project_spend_limit_exceeded",
) => ApiError::QuotaExceeded,
Some("insufficient_quota" | "credit_balance_exhausted") => ApiError::QuotaExceeded,
Some("usage_not_included") => ApiError::UsageNotIncluded,
Some("cyber_policy") => ApiError::CyberPolicy {
message: cyber_policy_message(error.message),
@@ -115,6 +115,18 @@ async fn terminal_failure_with_retry_header_ends_stream_immediately() {
for (code, expected) in [
("flex_unavailable", CodexErrorInfo::FlexUnavailable),
("budget_reached", CodexErrorInfo::SessionBudgetExceeded),
(
"api_key_spend_limit_exceeded",
CodexErrorInfo::ApiKeySpendLimitExceeded,
),
(
"project_spend_limit_exceeded",
CodexErrorInfo::ProjectSpendLimitExceeded,
),
(
"organization_spend_limit_exceeded",
CodexErrorInfo::OrganizationSpendLimitExceeded,
),
("inference_hook_denied", CodexErrorInfo::InferenceHookDenied),
(
"context_length_exceeded",