GloopAPI 연동 가이드
오류 처리
오류와 재시도 범위를 처리합니다.
재시도 여부를 결정하기 전에 요청이 접수되었는지 판단하세요. 엔드포인트 페이지에는 실제 상태 코드, 오류 응답 형식과 대표 오류가 나와 있습니다. 프로토콜마다 JSON 구조가 같지는 않으며 성공 시 바이너리를 반환하는 요청도 실패 시 JSON을 반환할 수 있습니다.
응답에 따른 판단
| 신호 | 다음 단계 |
|---|---|
| 400 / 지원하지 않는 필드 또는 모델 | 엔드포인트 스키마와 현재 기능 카탈로그에 맞게 입력을 수정하고 변경 없이 반복 재시도하지 마세요 |
| 401 / 403 | 키 만료, 계정, IP, 모델 또는 도구 권한과 할당량을 확인하세요 |
| 402 / 할당량 부족 | 예산을 늘리거나 새 요청의 범위를 줄이세요. 기존 작업은 원래 기록을 계속 복구하세요 |
| 404 | 리소스 식별 정보, 경로와 기능 스위치를 확인하세요. 제출 결과가 불명확한 요청이 실행되지 않았다고 추정하지 마세요 |
| 409 | 멱등성 충돌, 준비되지 않은 작업, 견적 변경과 참조된 리소스를 구분하고 구체적인 오류에 맞게 처리하세요 |
| 410 | 원래 리소스가 삭제되거나 만료되었습니다. 요금과 멱등성 증거를 보존하고 다른 작업을 자동 생성하지 마세요 |
| 429 / 5xx / 네트워크 시간 초과 | 요청 제한에 따라 대기하거나 서비스 복구를 기다린 뒤 접수 여부를 확인하세요. 멱등성 계약이 있을 때만 안전하게 재전송할 수 있습니다 |
접수된 요청과 불명확한 요청
HTTP 202는 접수되었거나 아직 완료 대기 중임을 뜻합니다. 도구가 HTTP 200을 반환해도 실패한 작업일 수 있으므로 status를 읽으세요. 취소 접수는 취소된 종료 상태가 아닙니다. HTTP 200 스트리밍 응답에도 오류 이벤트가 있거나 비정상 종료될 수 있습니다.
생성 시간 초과, unknown과 billing_review에는 원래 키를 유지하고 비동기 복구로 조회하세요. 저장 재시도와 재생성은 서로 다른 작업입니다. 저장 재시도로도 만료된 파일 소스를 복구하지 못할 수 있습니다.
진단 정보
시각, 메서드, 경로, HTTP 상태, 오류 코드, 제공된 request_id, 작업 ID와 비즈니스 요청 키를 기록하세요. 요청의 민감 정보는 가리고 API 키나 서명 URL은 기록하지 마세요. API가 반환한 오류 정보와 사용 기록으로 진단하세요.
자동 재시도에는 횟수와 시간 한도가 있어야 합니다. 접수되지 않았음을 입증할 수 없다면 유료 요청을 조사하세요. 중복 제출을 기본 복구 전략으로 사용하지 마세요.
안정적인 도구 오류 코드
| 기계 판독 코드 | HTTP | 안전한 처리 |
|---|---|---|
| invalid_input | 400 | 정확한 버전과 input_schema를 확인하고 새 요청의 입력을 수정하세요 |
| invalid_cursor | 400 | 커서를 직접 만들지 말고 첫 페이지를 새로 고쳐 새 next_cursor를 받으세요 |
| quote_required / budget_required | 400 | 새 호출의 기능 필드에 따라 필요한 견적이나 비용 상한을 추가하세요 |
| quote_expired / quote_stale / invalid_quote | 409 | 제출되지 않았음이 확인된 새 호출만 다시 확인하고 견적을 받으세요. 존재하지 않는 견적과 다른 사용자의 견적은 모두 소유자를 노출하지 않고 invalid_quote를 반환합니다 |
| budget_exceeded | 409 | 새 호출의 예산이 부족합니다. maximum_usd를 확인하고 예산을 명시적으로 선택하세요 |
| idempotency_conflict | 409 | 동일한 요청 키의 요청 내용이 변경되었습니다. 원래 전체 요청을 복구하고 새 키로 자동 재전송하지 마세요 |
| tool_service_unavailable | 503 | 인프라 장애 또는 일시적 기능 중단입니다. 결과가 불명확한 제출은 원래 식별 정보, 키와 전체 요청으로 복구하세요 |
생성 결과가 불명확하면 먼저 원래 run_id를 조회하세요. run_id가 없다면 원래 API 키, 원래 Idempotency-Key와 원래 quote_id 및 max_cost_usd를 포함한 원래 전체 생성 요청으로 재전송하세요. 견적이 만료되거나 스위치가 꺼졌다는 이유로 결과가 불명확한 제출을 수정하지 마세요. 새 견적이나 새 요청 키는 접수되지 않았음이 확인된 새로운 비즈니스 작업에만 적합합니다.