エラー
RFC 9457 problem details、status の扱い、retry 方針を説明します。
このガイドでは、problem body の読み方、各 HTTP status の扱い方、非同期 resource のエラーの解釈方法を説明します。
Synchronous /api/v1alpha1 HTTP errors use Content-Type: application/problem+json and RFC 9457. HTTP 200 asynchronous resources use a nested error object with code, title, detail, and next_action; it has no HTTP status member.
Problem body
{
"type": "https://developers.deepframe.cloud/errors/idempotency-in-flight",
"title": "Idempotency key is in use",
"status": 409,
"detail": "A request with this idempotency key is still being processed.",
"instance": "/api/v1alpha1/runs",
"request_id": "req_0190b5d4-7e1f-7a2b-9c3d-1234567890ab"
}| field | 用途 |
|---|---|
type | 安定した problem URI です。この値で client の処理を分岐してください。 |
title | 短い人間向け summary です。 |
status | HTTP status code です。 |
detail | この発生内容を説明する sanitized text です。 |
instance | request instance または route context です。 |
request_id | support と tracing に使う correlation id です。 |
errors | field 単位の validation detail です。 |
admission_constant | analysis request を拒否した capability constant です。 |
admitted_values | 指定された capability が受け付ける値です。利用可能な場合に返ります。 |
Status ごとの対応
- 400: malformed または schema-invalid request を修正してください。同じ request を retry しないでください。
- 401: キーまたは authentication header を修正してください。
- 402: quota または plan の変更を待ってください。
- 403: permission、billing state、trial state、またはワークスペースの alpha opt-in を修正してください。opt-in されていないワークスペースの有効なキーは
forbiddenになります。 - 404: resource id とキーの access を確認してください。
- 409: problem type を確認してください。
idempotency-in-flightなら待ち、conflict なら resource state の変更を待ってください。 - 422: input を修正してください。analysis admission failure は
admission_constantに拒否された capability を示します。 - 429:
Retry-Afterと rate-limit header に従ってください。 - 500: 安全に再実行できる operation だけ retry してください。
- 503: bounded exponential backoff と jitter で retry してください。
Retry では Idempotency-Key を保持してください
state-changing POST を retry するときは、同じ Idempotency-Key と同じ body を送ってください。同じ内容の replay は元の response を返します。異なる body は 422 idempotency-payload-mismatch になります。
Asynchronous Resource Errors
Poll the resource status as before. When an asynchronous resource fails, use error.code for client behavior and error.next_action for the next step. The nested error is separate from status, result_state, reason_code, and limitations.
Example response:
{
"status": "failed",
"error": {
"code": "processing_failed",
"title": "Video processing failed",
"detail": "The video could not be processed.",
"next_action": "Upload the video again."
},
"error_message": "The video could not be processed."
}error_message is deprecated. If present, it repeats the curated error.detail and does not expose stored internal failure text.
Problem type
エラーレジストリ にすべての problem type があります。主な type は bad-request、validation-error、unauthorized、forbidden、resource-not-found、conflict、idempotency-in-flight、unprocessable-entity、idempotency-payload-mismatch、rate-limit-exceeded、internal-error、service-unavailable です。
type で分岐し、detail や HTTP status だけで分岐しないでください。429 以外の 4xx を自動 retry しないでください。