エラーとレート制限

エラーレスポンスの形式、HTTP ステータスコードの一覧表、レート制限の挙動、そして Atlas Cloud で有効なリトライ戦略。

エラーレスポンスの形式

Atlas Cloud は、呼び出す API の種類に応じて 3 種類のエラー形式を返します。パーサーを書く前に、どの形式かを確認してください。

LLM プロトコルのエンドポイントとメディア生成エンドポイントで使われます:

{
  "code": 401,
  "msg": "unauthorized",
  "request_id": "…",
  "data": null
}

すべてのレスポンスには X-Request-ID ヘッダーが付きます。この値をログに残してください — サポートが特定の呼び出しを追跡する最短の手段です。

HTTP ステータスコード

ステータス	意味	対処
`400`	不正なリクエスト: パースできないボディ、`model` の欠落、誤ったコンテンツタイプ、無効な保持ヘッダー、無効な `webhook_url`	リクエストを修正してください。`msg` フィールドに具体的な問題が示されます
`401`	認証に失敗 — キーが未指定、不明、または期限切れ	キーを確認してください。誤った URL パスでも 401 が返るため、エンドポイントも確認してください
`402`	残高不足、または Coding Plan の利用枠を使い切った	チャージしてください
`403`	アカウントまたはユーザーに権限がない — Coding Plan のキーを、それを受け付けないモデルに使った場合を含みます	キーのスコープを確認するか、サポートにお問い合わせください
`404`	リソースが見つからない。モデルの場合は、アカウントから利用できないモデルも含みます	カタログと照らしてモデル ID を確認してください
`413`	リクエストボディが 50 MB を超えている	インラインの Base64 ではなく URL を送るか、先にファイルをアップロードしてください
`429`	レート制限に達した	バックオフしてリトライしてください — 詳細は後述します
`451`	お住まいの地域からはブロックされています	リトライ不可
`500`	内部エラー	一度リトライし、それでも失敗する場合はリクエスト ID を添えて報告してください
`503`	一時的に利用できません	バックオフしてリトライしてください
`504`	同期リクエストが最大待機時間を超えた	非同期フローに切り替えてポーリングしてください

401 は必ずしもキーが誤っていることを意味しません。ゲートウェイはルーティングの前に認証を行うため、パスのタイプミスでも 404 ではなく 401 になります。他の場所で動くキーであれば、まず URL を確認してください。

タスクレベルのエラーコード

非同期タスクが失敗すると、data.error_code に HTTP ステータスより具体的な数値のプラットフォームコードが入ります。たとえば 1039 は、入力がコンテンツモデレーションで拒否されたことを示します。

data.error には人間が読める説明が入ります。予測 ID と併せて、両方をログに残してください。

レート制限

レート制限はアカウント単位およびモデル単位で適用されます。上限を超えると 429 が返ります。

LLM およびメディアのエンドポイントは、X-RateLimit-Limit、X-RateLimit-Remaining、Retry-After を 返しません。残りのクォータをレスポンスヘッダーから読み取ることはできないため、クライアント側でバックオフを実装してください。

例外は /public/v1 の課金エンドポイントで、こちらの 429 レスポンスには Retry-After が含まれます。

本番ワークロードでより高い上限が必要な場合は、想定リクエスト量と利用モデルの構成を添えてお問い合わせください。

リトライ戦略

429、500、503、504 およびネットワークレベルの障害はリトライしてください。400、401、402、403、404、451 は リトライしないでください — 同じ結果になります。

読み取り リクエストは自由にリトライして構いません。生成リクエストの再送には注意してください。タイムアウトしたリクエストでも受理されている可能性があり、無条件にリトライすると 2 つ目のタスクが作られ、その分が課金されることがあります。非同期で送信してポーリングする方式なら、レスポンスを取りこぼしてもタスクを失うことはありません。

import time, random, requests

RETRYABLE = {429, 500, 503, 504}

def call_with_retry(url, payload, api_key, max_attempts=4):
    for attempt in range(max_attempts):
        response = requests.post(
            url,
            json=payload,
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=60,
        )
        if response.status_code not in RETRYABLE:
            return response

        if attempt == max_attempts - 1:
            break

        # 指数バックオフ + ジッター。多数のクライアントが同時にリトライするのを防ぐ
        delay = min(2 ** attempt, 30) * (0.5 + random.random() / 2)
        time.sleep(delay)

    return response

ストリーミング時のエラー

ストリーミングリクエストがストリームの開始前に失敗した場合は、通常の HTTP エラーが返ります。ストリームが始まった後は接続が維持されたまま、エラーはストリーム内のイベントとして届きます — つまりストリーミング呼び出しの 200 は、完全なレスポンスを保証しません。ストリームの途中終了は必ずハンドリングしてください。

ストリームには、キープアライブ用に : で始まる SSE コメント行が含まれることもあります。これらはデータではないので無視する必要があります — ほとんどの SSE クライアントは自動で処理しますが、自作パーサーでは見落としがちです。

サポートを受けるには

問題を報告する際は、次の情報を添えてください:

失敗したレスポンスの X-Request-ID ヘッダー
非同期タスクの場合は予測 ID
正確なモデル ID とタイムスタンプ

サポートからご連絡ください。

エラーレスポンスの形式

HTTP ステータスコード

タスクレベルのエラーコード

レート制限

リトライ戦略

ストリーミング時のエラー

サポートを受けるには

関連ドキュメント

LLM API プロトコル

予測

API キー

On this page