製品・APIガイド
エラー
エラーはRFC 9457のproblem+json形式で返されます。すべてのレスポンスにはcorrelationIdが含まれるため、サポートへのお問い合わせ時にお伝えください。
| ステータス | 意味 | 対処方法 |
|---|---|---|
401 | キーがないか、無効です | X-PDFgine-Keyヘッダーと、キーが取り消されていないことを確認してください。 |
402 | 利用枠を使い切りました | プランをアップグレードするか、期間の更新をお待ちください。 |
404 | テンプレートまたはドキュメントが見つかりません | テンプレートコードと、公開済みの改訂版があることを確認してください。 |
429 | レート制限を超えました | Retry-Afterヘッダーに記載された秒数だけ待って、再試行してください。 |
レート制限はプランで決まります
生成エンドポイントの1分あたり・1時間あたりの上限は、テナント単位でプランに基づいて適用されます。以下の表で確認できます。キー単位ではなくテナント単位のため、APIキーを追加しても上限は増えません。429レスポンスでは、X-PDFgine-RateLimit-Scopeヘッダーに、到達した時間枠がtenant-api、tenant-render-minute、tenant-render-hourのいずれかで示されます。一括処理では、1リクエストにつき1ドキュメントではなく、1つの/document-batchesリクエストで最大100件のドキュメントを送信してください。
利用枠を使い切った場合のレスポンス
HTTP/1.1 402 Payment Required
X-PDFgine-Quota-Remaining: 0
X-PDFgine-Metering-Basis: pdf-equivalent
{
"title": "ページ数の上限を超えました",
"status": 402,
"detail": "ご利用のプランのページ利用枠を使い切りました。",
"correlationId": "114249cb1dbc52a29026ab2eca5c4b72"
}Retry-Afterと制限時間枠
2つの上限が順に適用されます。最初はサービス保護のための認証情報ごとの上限で、60秒の時間枠に、キーなしで30件、キーありで120件のリクエストを許可します。次はプランに基づくテナントごとの上限です。
| プラン | ドキュメント / 分 | ドキュメント / 時間 |
|---|---|---|
| 無料 | 15 | 150 |
| Go | 30 | 300 |
| Pro | 60 | 600 |
| Max | 300 | 3,000 |
HTTP 429
HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-PDFgine-RateLimit-Scope: tenant-render-minute
{
"title": "Too many requests",
"status": 429,
"detail": "The request limit was exceeded. Please try again later.",
"correlationId": "505aac87e234a7b4669e6203ac7ffcd5"
}時間枠はスライド式ではなく固定式です。最初のリクエストで始まり、その中のすべてのリクエストは同じ利用枠に加算され、終了すると件数がリセットされます。Retry-Afterは、その時間枠の残り秒数です。その時間だけ待てば十分で、それより早く再試行しても、拒否が1回増えるだけです。
よくある問題
- 変更せずに4xxを再試行すると、再び失敗します。これはサービスの混雑ではなく、リクエストの誤りを示します。再試行すべきなのは429と5xxです。
- 429には、すでにRetry-Afterが含まれています。独自の推測で待機すると、時間を無駄にするか、再び拒否されます。
- 402は、深夜3時に誰かを呼び出すような障害ではありません。当月の利用枠を使い切ったことを示します。X-PDFgine-Quota-Remainingを監視し、到達前にプランをアップグレードしてください。
- ダウンロード時の410は、ファイル紛失ではありません。保存期間が終了したことを示します。ドキュメントは生成・集計された後、プランのスケジュールに従って削除されています。
- ステータスコードだけを記録すると、サポート時に推測が必要になります。correlationIdも一緒に記録してください。その値でリクエストを特定できます。