오류

{
  "code": "insufficient_balance",
  "error": "Not enough funds",
  "request_id": "9f3c1e2a7b4d5e60"
}

code로 분기하세요. 일부 오류에는 추가 필드가 있습니다:

{
  "code": "invalid_targeting",
  "error": "Unknown city",
  "field": "city",
  "value": "nosuchcity"
}
{
  "code": "unsupported_field",
  "error": "Field is not supported here",
  "field": "count"
}
{
  "code": "rate_limited",
  "error": "Too many requests",
  "retry_after": 12,
  "limit": 120
}

GET /api/v1/orders/{id}의 404에는 code 없이 error와 request_id만 있습니다.

코드 목록

코드	상태	발생 시점
invalid_api_key	401	키가 거부됨
validation_failed	400	필드 제약 조건 위반
invalid_body	400	본문 또는 필드의 형식이 잘못됨
unknown_product	400	슬러그를 알 수 없거나 판매하지 않는 상품
insufficient_scope	403	키에 라우트가 요구하는 권한이 없음
not_found	404	리소스가 없거나 다른 계정 소유
idempotency_in_progress	409	이 키로 보낸 이전 요청이 아직 실행 중
replace_in_progress	409	패키지 주소 교체가 이미 진행 중
invalid_volume	422	용량이 상품의 허용 범위 밖
invalid_quantity	422	한 번의 구매로 살 수 있는 수보다 많은 주소
country_unavailable	422	이 상품으로는 해당 국가를 판매하지 않음
unknown_plan, unknown_operator, unknown_period	422	선택한 국가에 해당 요금제, 위치 또는 기간이 없음 - 옵션을 확인하세요
out_of_stock	422	위치에 비어 있는 주소가 요청보다 적음
unsupported_capability	422	이 패키지 종류와 관계없는 작업
package_expired	422	주소 패키지의 기간이 끝남 - 먼저 연장하세요
prolong_window_closed	422	연장으로 더 이상 주소를 되찾을 수 없음 - 새 구매 필요
type_unavailable	422	구성을 평가할 수도 판매할 수도 없음
insufficient_balance	422	잔액 부족
unsupported_field	422	본문에 적용할 수 없는 키가 있음. field와 함께 옴
invalid_targeting	422	지역 카탈로그에 없는 값. field, value와 함께 옴
package_unavailable	422	패키지의 현재 상태나 이 설정으로는 작업 불가
purchase_refunded	422	구매가 성사되지 않음, 금액 반환됨
idempotency_key_required	422	Idempotency-Key 헤더 없음
idempotency_key_invalid	422	헤더가 비어 있거나 255자 초과
idempotency_key_reused	422	같은 키에 다른 본문
rate_limited	429	키의 요청 한도 소진
replace_cooldown	429	최근에 주소를 교체함. 다시 가능한 시점은 replace_available_at에 있음
order_failed	500	주문이 접수되지 않음, 잔액 차감 안 됨
package_failed	500	패키지 작업 실패, 금액 차감 안 됨
order_needs_attention	500	금액 차감됨, 발급되지 않음, 수동으로 처리 중
operation_indeterminate	500	결과가 확정되지 않은 작업의 키로 재시도함
catalog_unavailable	503	상품의 지역 카탈로그가 아직 동기화되지 않음

유료 작업

코드	금액	조치
order_failed, package_failed	차감 안 됨	같은 Idempotency-Key로 재시도
purchase_refunded (422)	반환됨	새 키로 새 구매처럼 재시도
order_needs_attention	차감됨, 결과 확인 중	재시도하지 말고 order_id와 함께 지원팀에 문의
operation_indeterminate	결과 미확정	같은 키로 재시도하지 말고 주문과 패키지를 확인한 뒤 지원팀에 문의

5xx의 메시지는 중립적입니다 - code로 분기하세요.

지원: @ipvrent_support, [email protected]. 오류 본문의 request_id와, 있다면 order_id를 첨부하세요.

재시도

타임아웃은 실패가 아닙니다: 요청이 도달했을 수 있습니다. 같은 Idempotency-Key로 재시도하면 같은 응답이 돌아옵니다. 409 idempotency_in_progress를 받으면 기다렸다가 같은 키로 재시도하세요.

재시도하지 않는 코드: insufficient_balance, invalid_volume, invalid_quantity, unknown_product, unsupported_field, unsupported_capability, invalid_targeting, prolong_window_closed. rate_limited는 Retry-After만큼, replace_cooldown은 replace_available_at까지 기다리세요.