Error envelope — Codens Help

共通エラー形式

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "detail": "Rate limit exceeded",
  "error_code": "RATE_LIMITED",
  "category": "transient",
  "retry_after_seconds": 12,
  "suggested_action": "exponential_backoff"
}

category は permanent / transient / unauthorized / budget_exceeded のいずれか。suggested_action は agent への hint（refresh_token / top_up_credit / exponential_backoff / fix_request_payload）。

主な `error_code` と retry semantics

error_code	HTTP	意味	retry semantics
`VALIDATION_ERROR`	400 / 422	request body / query parameter のバリデーション失敗。`detail` に該当フィールド情報。	retryable: false（修正必要）
`UNAUTHORIZED`	401 / 403	token 無効 / 期限切れ / scope 不足。`codens-mcp login` で再認証。	retryable: true（再ログイン後）
`CREDIT_INSUFFICIENT`	402	credit 残高不足。Pricing ページまたは Auth Codens のダッシュボードから top up。	retryable: false
`RESOURCE_NOT_FOUND`	404	repo / PRD / task / workflow run など対象リソースが存在しない / 別 org の所有。	retryable: false
`RATE_LIMITED`	429	rate limit 超過。`Retry-After` ヘッダ / `retry_after_seconds` を respect。	retryable: true（指数バックオフ）
`INTERNAL_ERROR`	500 / 503	サーバ側の予期せぬエラー。`detail` と request ID を含めて support に連絡。	retryable: true（短い backoff）
`IDEMPOTENCY_CONFLICT`	409	同じ Idempotency-Key が異なる payload で再送された。	retryable: false（key を変更するか元 payload に揃える）
`JWT_EXPIRED` / `JWT_INVALID` / `JWT_REPLAYED`	401	service 間 JWT の検証失敗。Auth Codens から token を取り直す。	retryable: true（再認証後）
`ORG_NOT_LINKED_TO_AUTH` / `ORG_NOT_FOUND`	403 / 404	cross-service で渡した `organization_id` が当該サービスに存在しない / link されていない。`organization_id` 省略推奨（credentials から自動解決される）。	retryable: false
`SERVICE_DISABLED`	403	該当 org でそのサービスが無効化されている。	retryable: false

Cross-service の organization_id 注意

Red / Blue / Green / Purple は各サービスに独立した organization_id を持ちます。あるサービスで取得した org ID を別サービスに渡すと UNAUTHORIZED / ORG_NOT_FOUND になります。codens-mcp v0.7.5 以降は organization_id を省略すれば各サービスの /api/v1/auth/me から自動解決されるため、明示的に渡す必要はありません。

Error envelope 仕様

共通エラー形式

主な error_code と retry semantics

主な `error_code` と retry semantics