오류

Webway의 오류 응답, 상태 코드 및 안전한 재시도 방식을 알아보세요.

오류는 OpenAI 호환 SDK가 파싱할 수 있는 작은 JSON 엔벌로프를 사용합니다.

json

{
  "error": {
    "message": "insufficient credit",
    "type": "insufficient_quota",
    "code": "insufficient_quota"
  }
}

type은 클라이언트 라이브러리가 분기 기준으로 사용하는 대략적인 값입니다. code는 더 구체적이며, 제공업체 측에서 실패한 경우에만 type과 다릅니다.

엔벌로프 형식은 엔드포인트에 맞춰집니다. /v1/messages는 Anthropic 형식을 반환하므로 Anthropic SDK와 Claude Code가 이를 파싱하고 이 게이트웨이에 별도 예외 처리를 하지 않아도 자체 재시도 로직을 적용할 수 있습니다.

json

{
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "the provider is over capacity, retry shortly (request 4f2ab910)",
    "code": "overloaded"
  }
}

상태 코드

상태	의미	재시도?
`400`	JSON, 필드 또는 매개변수가 잘못됨	아니요. 요청을 수정하세요
`401`	API 키가 없거나, 유효하지 않거나, 만료되었거나, 취소됨	아니요. API 키를 교체하세요
`402`	잔액으로 요청 비용을 충당할 수 없음	크레딧 충전 후
`403`	모델에 자체 제공업체 API 키가 필요함	아니요. 대시보드에서 추가하세요
`404`	모델 또는 엔드포인트를 찾을 수 없음	아니요. ID와 경로를 확인하세요
`413`	요청 본문이 너무 큼	아니요. 페이로드를 줄이세요
`429`	속도 제한에 도달함	예. 기다렸다가 재시도하세요
`502` / `503`	제공업체를 사용할 수 없음	예. 백오프를 사용하세요
`504`	제공업체 응답 시간이 초과됨	예. 백오프를 사용하세요

402는 오직 잔액에 관한 오류입니다. Webway와 제공업체 사이의 결제 문제는 사용자가 조치할 수 있는 문제가 아니므로 502입니다.

제공업체 오류

사용자의 요청이 아니라 제공업체에서 오류가 발생하면 code가 오류 유형을 나타냅니다.

`code`	상태	의미	재시도?
`model_unavailable`	`502`	제공업체가 이 모델을 제공하지 않음. Webway에서 해결할 문제	아니요
`context_length_exceeded`	`400`	요청이 모델의 컨텍스트 창보다 김	아니요
`content_filtered`	`400`	제공업체의 안전 계층이 요청을 거부함	아니요
`invalid_request`	`400`	제공업체가 요청을 거부함	아니요
`rate_limited`	`429`	제공업체에서 속도가 제한됨	예
`overloaded`	`503`	제공업체의 처리 용량이 부족함	예
`timeout`	`504`	제공업체가 제시간에 응답하지 않음	예
`transport_error`	`502`	제공업체 연결에 실패함	예
`upstream_error`	`502`	분류되지 않음. 항상 조사 대상	경우에 따라

제공업체의 오류 문구는 그대로 전달되지 않습니다. 업스트림은 자체 용어로 오류를 설명하며, 때로는 다른 언어를 사용하고, 사용자의 것이 아닌 인프라를 언급하는 경우가 많으며, 그 문구가 예고 없이 바뀌기도 합니다. 모든 오류는 위 유형 중 하나로 분류되어 다시 작성되므로, 사용자가 받는 메시지는 로그에서 기준으로 삼을 수 있을 만큼 일관됩니다.

각 메시지 끝에는 Webway 요청 ID가 있습니다. 지원 요청 시 이 ID를 알려주세요. 실제로 조회할 수 있는 식별자입니다.

응답 헤더가 이미 전송된 후 요청이 실패할 수 있습니다. 이 시점에는 상태 코드를 변경할 수 없으므로, 오류는 나머지 스트림과 같은 프로토콜의 이벤트로 전달됩니다. /v1/messages에서는 event: error, /v1/responses에서는 error 이벤트, /v1/chat/completions에서는 error 청크로 전달됩니다. code 값은 위 표와 같습니다.

종료 이벤트 없이 끝난 스트림은 짧은 답변이 아니라 실패로 처리하세요.

재시도 규칙

429와 일시적인 5xx 응답만 재시도하세요. 지터를 적용한 지수 백오프를 사용하고, 시도 횟수에 상한을 두며, Retry-After가 있으면 이를 따르세요.

400, 401, 402, 403, 404 또는 413은 요청을 변경하지 않은 채 재시도하지 마세요. 같은 요청은 다시 실패합니다.

제공업체의 작업이 시작되기 전에 거부된 요청에는 요금이 부과되지 않습니다. 생성이 시작된 후 실패한 요청에는 이미 생성된 토큰에 대한 요금이 부과될 수 있으며, 스트리밍 도중 취소한 요청도 여기에 포함됩니다.

오류

상태 코드

제공업체 오류

스트리밍 중 오류

재시도 규칙