오류 처리

모든 엔드포인트의 모든 오류는 하나의 봉투 형식을 사용합니다.

{
  "error": {
    "code": "not_found",
    "message": "Link not found",
    "doc_url": "https://linkprofit.com/docs/api/errors"
  }
}

처리 분기는 error.code로 하고, 사람에게는 error.message를 보여 주십시오. 검증 오류에는 필드별 메시지를 담은 details 배열이 함께 옵니다.

{
  "error": {
    "code": "validation_failed",
    "message": "Request failed validation",
    "doc_url": "https://linkprofit.com/docs/api/errors",
    "details": [
      { "path": "url", "message": "Destination URL is not a valid address" }
    ]
  }
}

오류 코드

| 코드 | HTTP | 의미 | 대처 방법 | |---|---|---|---| | unauthorized | 401 | 키가 없거나, 알 수 없거나, 폐기되었거나, 만료됨 | 헤더를 확인하고 새 키를 발급하십시오 | | forbidden | 403 | 엔드포인트에 맞지 않는 키 종류이거나, 허용되지 않는 작업 | 문서에 따라 워크스페이스 키 또는 파트너 키를 사용하십시오 | | insufficient_scope | 403 | 키에 필요한 스코프가 없음 | 메시지에 표시된 스코프를 가진 키를 만드십시오 | | plan_restricted | 403 | 요금제에 이 기능이 포함되어 있지 않음 | 요금제를 상향하거나 요청에서 해당 기능을 빼십시오 | | not_found | 404 | 리소스가 존재하지 않거나, 다른 테넌트의 것임 | id를 확인하십시오. 남의 리소스는 존재하지 않는 것과 구분되지 않습니다 | | invalid_request | 400 | 잘못된 형식의 JSON, 잘못된 커서, 어긋난 비즈니스 규칙 | 요청을 고치십시오 | | validation_failed | 422 | 본문이나 쿼리가 스키마 검증을 통과하지 못함 | details에 나열된 필드를 고치십시오 | | conflict | 409 | 상태 충돌: 이미 사용 중인 슬러그, 다른 본문으로 재사용된 Idempotency-Key | 다른 값을 고르거나 새 멱등 키를 쓰십시오 | | quota_exceeded | 422 | 요금제 할당량 소진(링크, 도메인, 고객) | 요금제를 상향하거나 할당량을 확보하십시오 | | rate_limited | 429 | 이 키로 보낸 요청이 너무 많음 | Retry-After 초만큼 기다리십시오. 요청 제한 참고 | | not_configured | 503 | 이 환경에서는 해당 기능이 설정되어 있지 않음 | 나중에 다시 시도하거나 지원팀에 문의하십시오 | | internal | 500/502/504 | 예기치 못한 플랫폼 오류 | 대기 시간을 늘려 가며 재시도하고, 계속되면 알려 주십시오 | | invalid_click_id | 422 | click_id가 위조되었거나, 변조되었거나, 다른 워크스페이스에서 발급된 것임 | 클릭 식별자 파라미터의 값을 도착 주소에 있던 그대로 전달하십시오 | | attribution_expired | 422 | 클릭이 워크스페이스의 기여 기간보다 오래됨 | 재시도할 것이 없습니다. 필요하면 대시보드에서 기간을 조정하십시오 |

알아 두면 이득인 처리 규칙

• 404는 격리 장치이기도 합니다. 다른 워크스페이스의 id는 forbidden이 아니라 언제나 not_found를 반환합니다. API는 남의 id가 존재하는지 여부를 드러내지 않습니다.
• 안전한 것만 재시도하십시오. internal과 rate_limited는 대기 시간을 늘려 가며 재시도하십시오. conflict와 validation_failed는 요청 자체가 잘못된 것이므로 무턱대고 재시도해서는 안 됩니다. 변경 요청을 안전하게 재시도하려면 Idempotency-Key를 쓰십시오.
• GET /links는 404를 내지 않습니다. 조건에 맞는 항목이 없으면 빈 목록이 반환됩니다. 컬렉션 자체에 404를 쓰면 의미가 모호해집니다.