오류와 속도 제한 다루기

문서화된 모든 오류는 똑같은 세 필드 JSON 봉투를 써요.

{
  "code": "invalid_param",
  "message": "user is required",
  "status": 400
}

출처: 공식문서

status는 HTTP 상태를 그대로 비추고, code는 분기할 때 쓰는 안정적인 식별자, message는 사람이 읽을 수 있는 상세 내용이에요. 각 엔드포인트 페이지는 정확히 어떤 코드를 낼 수 있는지 나열해 둡니다.

상태 클래스 한눈에 보기

Status	의미	전형적인 코드
400	요청 또는 앱 설정이 유효하지 않음	`invalid_param`, `bad_request`, `app_unavailable`, provider 오류(아래)
401	API 키 누락 또는 유효하지 않음	`unauthorized`
403	키가 여기서 행동할 수 없음: 접근 제한 또는 플랜 한도	`forbidden`
404	리소스가 없거나 이 키/`user`에 보이지 않음	`not_found`
413 / 415	파일이 너무 크거나 지원하지 않는 유형	`file_too_large`, `unsupported_file_type`
429	지금 요청이 너무 많거나 할당량 소진	`too_many_requests`, `rate_limit_error`
500	Dify 쪽에서 뭔가 실패함	`internal_server_error`

Provider 오류는 설정 오류

네 가지 흔한 400 코드는 요청이 아니라 앱의 모델 설정을 가리켜요.

provider_not_initialize: 유효한 모델 자격증명이 없음
provider_quota_exceeded: 모델 제공자 자체의 할당량이 소진됨
model_currently_not_support: 모델이 현재 지원되지 않음
completion_request_error: completion 요청 중 오류 발생

이 오류들엔 재시도가 소용없어요. Dify에서 앱의 모델 설정을 고쳐야 합니다.

속도 제한과 할당량

429 코드 두 개는 의미가 달라요.

too_many_requests는 동시성 상한 — 지금 그 앱에 동시 요청이 너무 많아요. 물러났다가 재시도하세요.
rate_limit_error는 Dify Cloud의 플랜 할당량(예: 워크플로 실행 횟수)이에요. 재시도로 해결되지 않고, 할당량 주기가 돌거나 플랜이 바뀌어야 초기화됩니다.

Dify Cloud에서 지식 베이스 쓰기 엔드포인트는 플랜 한도를 403 응답으로 강제하기도 해요. 이들은 접근 제한과 같은 forbidden 코드를 갖는데, 플랜 한도인지 알려주는 건 message예요. 그래서 403에선 code만으로 분기하지 마세요.

스트림 안의 오류

스트림이 열리면 HTTP 상태는 이미 200이에요. 실패는 error 이벤트로 도착해 스트림을 끝냅니다. 이벤트의 code 값은 여기 문서화된 것과 같으니, 같은 규칙으로 분류하면 돼요. 자세한 건 스트리밍 응답 소비하기를 참고하세요.

뭘 재시도할까

백오프와 함께 재시도: too_many_requests, 500, 네트워크 실패.
그대로 재시도하면 안 됨: 검증 오류(요청을 먼저 고쳐야 함), 인증 실패, 할당량 오류(할당량이 풀릴 때까지 해결 안 됨).
재시도가 아니라 고치기: 재개 호출에서 난 404는 user가 잘못됐거나 실행이 없다는 뜻이에요. 식별자를 고치세요.

오류와 속도 제한 다루기