エラー

API 固有のエラーは RFC 7807 Problem Details 形式で返ります。HTTP status だけでなく、機械可読な code で分岐してください。

エンドポイントごとの返却可能な code は API Reference の Responses にも載せています。

リクエスト body、query parameter、path parameter の型や必須項目が FastAPI / Pydantic validation に失敗した場合は、422 の validation error が application/json で返ります。このレスポンスにはモモンガサーチ API 固有の code は含まれません。

4xx / 5xx / 429 は credits を消費しません。429 では Retry-After を見て再試行タイミングを決めてください。通常レスポンスでは X-RateLimit-* を返し、plan に上限がある場合は X-Quota-Catalog-* / X-Quota-Compute-* も返します。

レスポンス例

{
  "type": "https://api.momongasearch.com/errors/content-not-available",
  "title": "Content not available",
  "status": 409,
  "code": "content_not_available",
  "detail": "This document content is pending release.",
  "document_id": "doc_...",
  "content_status": "pending_release",
  "retry_after_seconds": 3600
}

代表的な `code`

code	HTTP status	意味
`authentication_required`	401	Authorization ヘッダーがない
`invalid_api_key`	401	API キーが無効
`access_not_enabled`	403	API キーは有効だが、アカウントに有効な entitlement がない
`missing_required_filter`	400	市場全体の一覧で `timeline_since` がないなど、必要な絞り込み条件がない
`invalid_date_range`	400	`timeline_since` が `timeline_until` より後
`invalid_cursor`	400	`cursor` が壊れている、期限切れ、または現在のフィルタと一致しない
`invalid_document_family`	400	`document_families` に未対応の値が含まれる
`invalid_macro_tag`	400	`macro_tags` に public v1 で未対応の値が含まれる
`invalid_query_parameter`	400	配列 query parameter がカンマ区切りで指定されているなど、指定形式がサポート外
`invalid_section`	400	`/content?sections=...` に、対象文書で使えない `section_id` が含まれる
`not_found`	404	指定したリソースが存在しない
`content_not_available`	409	本文・目次・元ファイルが取得できない
`image_not_available`	409	ページ画像が取得できない
`rate_limit_exceeded`	429	レート制限を超過
`quota_exceeded`	429	credit API credits または日次リクエスト上限を超過
`internal_error`	500	サーバー側で処理に失敗
`search_backend_timeout`	504	検索バックエンドがリクエスト期限内に応答しなかった

rate_limit_exceeded は、API キー単位の毎分リクエスト数に達した場合に返ります。Retry-After と X-RateLimit-Reset を見て、exponential backoff と jitter を入れて再試行してください。Edge protection による短時間の連続リクエスト制限では、Problem Details 形式ではない 429 が返る場合があります。

quota_exceeded は、日次リクエスト上限や credit API credits など、明示された利用上限を使い切った場合に返ります。credit API ではバックエンド実行前に credits を確認するため、quota 超過時は検索バックエンドやファイル取得処理を実行しません。プランごとの上限は Pricing を参照してください。

公開 Pricing に載せている主要な quota 以外にも、サービス保護のための追加制限が適用される場合があります。429 を無視して継続すると、API キーの一時制限、停止、または個別契約の相談対象になります。

image_not_available は、指定ページが文書のページ範囲内だが GET /v1/documents/{document_id}/page-images に含まれない場合に返ります。存在しない文書や範囲外ページは not_found です。取得可能なページ番号は /page-images で確認してください。

search_backend_timeout は、検索バックエンドがリクエスト期限内に応答しなかった場合に返ります。短い backoff を置いて再試行できますが、連続する場合は同じ条件で再試行し続けないでください。

未知のレスポンス code は汎用エラーとして扱い、クライアントが落ちないようにしてください。リクエストで使える enum や parameter は OpenAPI reference に出ている値だけです。