PDF Blocks
料金サポート
無料で始める
ページへ移動

エラー

problem+json のエラー形式、各ステータスコードの意味、失敗したリクエストをコードで処理する方法。

リクエストが失敗すると、PDF Blocks は標準的な HTTP ステータスコードと、何が問題だったかを示す機械可読な本文を返します。エラーは RFC 7807 の problem details に従うため、どのアクションが原因であっても同じ方法ですべての失敗を解析できます。

problem+json モデル

エラーレスポンスは Content-Type: application/problem+json を持ち、次の形をしています。

属性 型 説明
type string 問題に関するドキュメントへの URL。
title string 問題を人間が読める形で要約したもの。
status integer 本文にも反映される HTTP ステータスコード。
errors object フィールド名とエラーメッセージの配列を対応付けたもの。

type の URL は常にステータスコードで終わるため（例：https://www.pdfblocks.com/docs/api/v1/error/400）、この URL または status で分岐できます。errors オブジェクトは、失敗が特定のリクエストフィールドに結び付いている場合（バリデーション）に存在します。無効な API キーのようなリクエスト全体に対する失敗では、省略されることがあります。

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/400",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "file": [
      "Could not parse the PDF document. The file may be invalid or corrupt."
    ]
  }
}

ステータスコード

ステータス 意味 対応
400 バリデーションエラー 該当するフィールドを修正して再送信してください。
401 未認証 有効な X-API-Key を送信してください。
404 見つかりません アクションのルートとホストを確認してください。
406 受理できない Accept サポートされている形式をリクエストしてください。
402 支払いが必要 (予約済み) 請求またはクォータの問題を解決してください。
403 禁止 (予約済み) このキーはこの呼び出しを許可されていません。
413 ペイロードが大きすぎる より小さいファイルを送信してください。
429 リクエストが多すぎる (予約済み) 間隔を空けて再試行してください。
5xx サーバーエラー（まれ） バックオフして再試行してください。

400：バリデーションエラー

パラメーターが無効か、file が読み取り可能な PDF ではありません。errors オブジェクトが、問題のある各フィールドを示します。

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/400",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "line_1": ["The field line_1 must be a string with a maximum length of 32."]
  }
}

errors をフィールドごとに読み、入力を修正してから再送信してください。変更を加えない限り、400 は再試行しても成功しません。

401：未認証

X-API-Key ヘッダーが欠けているか、形式が誤っているか、有効なキーではありません。

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/401",
  "title": "The request is missing a valid API key.",
  "status": 401
}

ダッシュボード の有効なキーを X-API-Key ヘッダーに設定し、リクエストは HTTPS 経由で送信してください。詳細は 認証 を参照してください。

404：見つかりません

パスがどのアクションにも一致しません。多くの場合、アクション名のタイプミスか、バージョンのセグメントが抜けています。

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/404",
  "title": "The requested resource was not found.",
  "status": 404
}

ルート（例：/v1/add_text_watermark）と、呼び出し先が有効な ベース URL であることを確認してください。

406：受理できない Accept

複数のドキュメントを返すアクションが、満たせない Accept ヘッダーを受け取りました。

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/406",
  "title": "The requested Accept header cannot be satisfied.",
  "status": 406
}

サポートされている形式（application/zip、application/json、multipart/mixed）のいずれかをリクエストするか、Accept を省略してデフォルトの ZIP を取得してください。詳細は レスポンスフォーマット を参照してください。

413：ペイロードが大きすぎる

プランごとに、1つの入力ドキュメントの最大サイズが決まっています。Free では5MB、それ以外のプランでは10MBです（料金 を参照）。この上限を超える本文を持つリクエストは、処理前に拒否されます。429 とは異なり、413 は再試行しても成功しません。より小さいファイルを送信するか、上限の引き上げが定期的に必要な場合はご相談ください。

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/413",
  "title": "This request exceeds your plan's maximum document size of 10 MB.",
  "status": 413
}

予約済みのステータスコード

将来に向けた仕様です。 402、403、429 の各レスポンスは API 契約の一部ですが、現時点ではまだ強制されていません。有効化されたときにすぐクライアントが対応できるよう、今のうちに処理しておいてください。使用量とレート制限の詳細は レート制限と使用量 をご覧ください。

402：支払いが必要。 プランにおける請求またはクォータの条件です。

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/402",
  "title": "Payment is required to complete this request.",
  "status": 402
}

403：禁止。 キーは有効ですが、このリソースの利用を許可されていません。

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/403",
  "title": "You do not have permission to access this resource.",
  "status": 403
}

429：リクエストが多すぎる。 プランのレート許容量を超えました。

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/429",
  "title": "Too many requests. Please retry later.",
  "status": 429
}

5xx：サーバーエラー

5xx ステータスはこちら側の問題を示すもので、まれにしか発生しません。一時的な問題であるため、同じリクエストを指数バックオフを付けて再試行してください。

コードでのエラー処理

本文を一度だけ解析し、status（または type の末尾のステータス）で分岐します。

  • 400：errors オブジェクトを読み、各メッセージを対応するフィールドに突き合わせて入力を修正します。むやみに再試行しないでください。同じリクエストは再び失敗します。
  • 401、403、404、406：リクエスト自体に誤りがあります。ヘッダー、ルート、または Accept を修正して再送信してください。変更せずに再試行しても解決しません。
  • 402、413：アカウントまたはサイズに関する条件です。請求の問題を解決するか、より小さいファイルを送信してください。そのままでは再試行しても成功しません。
  • 429 と 5xx：一時的なものです。指数バックオフで再試行し、Retry-After ヘッダーがある場合はそれに従い、試行回数の上限を設けてください。詳細は レート制限と使用量 をご覧ください。

errors オブジェクトが存在する場合は必ず読んでください。修正すべき内容が正確に示されています。