규칙
ID, 타임스탬프, 오류 형식, 버전 관리 및 재시도.
| 관례 | 규칙 |
|---|---|
| ID | UUID는 불투명합니다. 전체를 그대로 저장하세요. 절대 파싱하거나 줄이지 마세요 |
| 타임스탬프 | UTC의 RFC 3339 형식, 예: 2026-09-22T04:10:00Z |
| 알 수 없는 필드 | 무시하세요. 새 응답 필드와 새 상태값은 버전 변경 없이 추가될 수 있습니다 |
| 버전 관리 | 접두사에 주요 버전이 포함됩니다. 호환성을 깨는 변경이 있으면 새 접두사와 사전 공지가 제공됩니다 |
| 오류 | {"description": "…", "error": {"error_code": "…", "error_attributes": {…}}} — 다음을 기준으로 분기 error.error_code, 로그에 기록 설명, 텍스트로는 절대 일치시키지 마세요. 참조: 오류 및 제한 |
| 재시도 | 준수하세요 Retry-After 429에서. 5xx에서는 지수 백오프와 지터를 사용해 재시도하세요 |
멱등성
전송하세요 idempotency_key 시작하는 모든 실행마다. 그것은 당신만의 문자열입니다 — 에피소드 번호, 작업 ID, 해당 작업 단위에서 안정적인 어떤 값이든 됩니다.
- 같은 키에 같은 본문을 사용하면 두 번째 실행을 시작하는 대신 이미 존재하는 실행을 반환합니다.
- 같은 키에 다른 본문을 사용하면 다음으로 거부됩니다
idempotency_conflict. 새 작업에는 새 키를 사용하세요.
이렇게 하면 시간 초과 후 재시도가 안전해집니다. 이것이 하나의 실행과 요금이 청구되는 중복 실행의 차이입니다.
추적
모든 응답에는 x-morphic-trace-id. 기록하세요. 문제를 보고할 때, 그 ID 덕분에 시간 범위를 묻지 않고도 몇 초 만에 실행을 찾을 수 있습니다.