Error codes

Status codes#

Response shapes#

Error bodies come in three shapes. Most carry a string or object inside detail; request-size and format errors use the OpenAI-compatible { error: { message, type } } shape. Schema validation failures (422) put an array in detail.

{
  "detail": {
    "error": "insufficient_credits",
    "message": "사용 가능 크레딧 부족: 12,000 크레딧 < 54,000 크레딧. 대시보드 → 결제에서 충전해주세요.",
    "action": { "type": "topup", "path": "/billing" }
  }
}

{
  "detail": {
    "error": "upstream_request_rejected",
    "message": "모델 제공자가 요청을 거부했습니다. 잠시 후 다시 시도하거나 다른 모델을 사용해주세요. (upstream 400: ...)",
    "retryable": false,
    "upstream": { "status": 400, "detail": "..." }
  }
}

{
  "error": {
    "message": "요청 본문이 너무 큽니다(최대 50MB).",
    "type": "payload_too_large"
  }
}

{
  "detail": [
    {
      "loc": ["body", "duration_seconds"],
      "msg": "Input should be between 2 and 20",
      "type": "greater_than_equal"
    }
  ]
}

Structured errors may include an action field with a dashboard path, plus retryable, providers, and upstream where applicable. message is always Korean — treat it as human guidance, not a parsing target.

Machine-readable codes#

Errors during streaming#

A stream: true request that fails mid-stream still returns HTTP 200, so the failure arrives as the final SSE event. The partial object holds the response received so far, and only that part is billed. With no partial output, data: [DONE] follows immediately.

data: {"error": {"code": "upstream_error", "message": "모델 제공자 연결이 중단되었습니다. 받은 부분까지만 과금됩니다.", "partial": {...}}}

data: [DONE]

Retry guidance#

Retry 429 and 502 (retryable=true) with exponential backoff. The text path already retries providers twice and falls back, so we recommend a client retry interval of at least 1 second. 4xx and retryable=false 502 keep failing until you fix the request.

Common errors and fixes#