페이지네이션, 멱등성, 오류 처리

Ody API는 목록 엔드포인트에서 불투명한 커서 페이지네이션, 안전한 메시지 전송 재시도를 위한 Idempotency-Key 헤더, 그리고 모든 응답에 요청 ID가 포함된 통일된 오류 엔벨로프를 사용합니다. 이 가이드에서는 이 세 가지를 모두 다룹니다.

커서 페이지네이션

GET /v1/api/contacts 및 GET /v1/api/conversations는 ?limit= 및 ?cursor=를 사용하여 페이지를 매깁니다:

curl "https://api.ody.co/v1/api/contacts?limit=100" \
  -H "Authorization: Bearer ody_live_…"

응답에는 nextCursor가 포함됩니다. 다음 페이지를 가져오려면 ?cursor=로 다시 전달하고, null이 되면 중지하세요:

{ "contacts": [ … ], "nextCursor": "eyJ…" }

• 커서는 불투명합니다. 항상 그대로 다시 전달해야 합니다. 수정되거나 오래된 커서는 400 invalid_argument를 반환합니다.
• 페이지 크기 제한: 연락처 기본값 50, 최대 200; 대화 기본값 50, 최대 100. GET /v1/api/messages/search (기본값 25, 최대 100) 및 GET /v1/api/calls (기본값 50, 최대 200)는 커서 없이 ?limit=만 사용합니다.
• 공식 SDK는 listAll() / list_all()을 사용하여 nextCursor를 자동으로 처리합니다. SDK 빠른 시작: TypeScript 및 Python을 참조하세요.

멱등성 메시지 전송

POST /v1/api/messages 후 네트워크 오류가 발생하면 메시지가 전송되었는지 알 수 없으며, 맹목적으로 재시도하면 이중 전송의 위험이 있습니다. Idempotency-Key 헤더(논리적 전송당 고유한 최대 200자 문자열)를 보내면 재시도가 안전해집니다:

curl https://api.ody.co/v1/api/messages \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{"to":"+15125550123","body":"Your order shipped!"}'

• 첫 번째 성공적인 응답은 24시간 동안 저장됩니다. 해당 기간 내에 동일한 키로 재시도하면 다시 전송하는 대신 저장된 응답이 그대로 재생되며, Idempotency-Replayed: true 응답 헤더가 추가됩니다.
• 키는 시도당 무작위 값이 아닌 자체 비즈니스 이벤트("order-1042-shipped")에서 파생해야 합니다. 핵심은 재시도가 키를 공유한다는 것입니다.

오류 엔벨로프

모든 오류 응답은 동일한 형식을 사용합니다:

{ "error": { "code": "permission_denied", "message": "This API key is missing the 'messages:send' scope", "requestId": "req_…" } }

상태	코드	처리 방법
400	invalid_argument	요청을 수정하세요. 메시지에 문제가 설명되어 있습니다.
401	unauthenticated	키가 없거나, 유효하지 않거나, 취소되었습니다. 재시도하지 말고 통합 소유자에게 알리세요.
403	permission_denied	메시지에 누락된 범위가 명시되어 있습니다. 해당 범위가 있는 키를 생성하세요.
404	not_found	이 작업 공간에 리소스가 존재하지 않습니다.
409	failed_precondition	작업 공간에서 아직 이 작업을 수행할 수 없습니다 (예: 보낼 활성 번호 없음). 사용자에게 알리고 재시도하지 마세요.
429	resource_exhausted	속도 제한됨 — Retry-After 초만큼 기다린 다음 백오프하여 재시도하세요.
500	internal	지수 백오프 및 지터로 재시도하고, 재시도 횟수를 제한하세요.

요청 ID

모든 응답(성공 또는 오류)에는 X-Request-Id 헤더가 포함되며, 오류 본문에서는 requestId로 반영됩니다. 이를 자체 요청 로그와 함께 기록하고, 지원팀에 문의할 때 인용하세요. 이를 통해 저희 측에서 정확한 요청을 찾아낼 수 있습니다. 또한 자체 X-Request-Id(최대 64자, 문자/숫자/_/-)를 제공할 수 있으며, Ody는 이를 다시 반영하여 재시도 상관 관계를 쉽게 파악할 수 있도록 합니다.

관련 문서

• API 개요 및 인증
• API 속도 제한 및 모범 사례
• SDK 빠른 시작: TypeScript 및 Python