오류 처리

앙크 Public API는 표준 HTTP 상태 코드와 세부 error 문자열을 포함한 일관된 JSON 포맷으로 오류를 반환합니다.

📌 기본 오류 응답 구조

모든 에러 응답은 다음 JSON 스키마를 따릅니다:

{
  "error": "idempotency_conflict",
  "message": "The idempotency key was already used with a different request payload.",
  "param": "idempotency_key"
}

🚦 HTTP 상태 코드별 의미

상태 코드	에러 코드	의미 및 권장 조치
`400 Bad Request`	`invalid_input`, `validation_failed`	요청 바디 또는 쿼리 파라미터 형식 오류. 요청 데이터 수정 필요.
`401 Unauthorized`	`unauthorized`, `invalid_api_key`	유효하지 않거나 누락된 Bearer 토큰. API 키 확인 필요.
`403 Forbidden`	`insufficient_scope`, `quota_exceeded`	API 키의 스코프 부족 또는 플랜 한도 초과.
`404 Not Found`	`not_found`	요청한 리소스(`content_id`, `connection_id` 등)가 존재하지 않음.
`409 Conflict`	`idempotency_conflict`	동일한 `idempotency_key`로 다른 페이로드가 이미 요청됨. 새 키 생성 필요.
`423 Locked`	`brand_locked`	요금제 만료 또는 정책 위반으로 브랜드가 잠김. 결제 관리 확인.
`429 Too Many Requests`	`rate_limited`	분당 API 호출 한도 초과. `Retry-After` 헤더 확인 후 대기.
`500 Server Error`	`internal_server_error`	앙크 서버 일시 오류. 지수 백오프로 재시도 가능.
`503 Service Unavailable`	`sns_provider_unavailable`	외부 SNS API 일시 장애. 나중에 재시도.

🔍 주요 비즈니스 에러 응답 예시

1. 403 Insufficient Scope (스코프 부족)

{
  "error": "insufficient_scope",
  "message": "The API key does not have the required 'publishing:create' scope."
}

2. 409 Idempotency Conflict (멱등성 키 충돌)

{
  "error": "idempotency_conflict",
  "message": "Idempotency key 'launch-001' is already bound to a different request hash.",
  "param": "idempotency_key"
}

3. 400 Media Validation Failed (미디어 검증 실패)

{
  "error": "sns_content_media_maximum_exceeded",
  "message": "Bluesky supports a maximum of 4 images per post.",
  "param": "media"
}

🔁 안전한 재시도(Retry) 전략

재시도 가능 (5xx, 네트워크 타임아웃): **동일한 idempotency_key**를 유지하면서 지수 백오프(Exponential Backoff with Jitter)를 적용하여 재전송하세요.
재시도 불가 (400, 401, 403, 404, 409): 클라이언트 코드나 요청 페이로드를 수정한 후 새 멱등성 키로 다시 요청해야 합니다.

🔗 관련 문서