エラーを処理する

リクエストが失敗すると、API はファイルの代わりに、error オブジェクトを含む JSON ボディを返します。

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid api key",
    "docs": "https://bannerify.co/docs/api-reference/errors/code/BAD_REQUEST",
    "requestId": "req:1a2b3c4d5e6f7a8b"
  }
}

フィールド	説明
code	エラーの種類を表す、変わらないコード。このフィールドで処理を分岐します
message	何が問題だったかを説明する文
docs	そのコードのページへのリンク
requestId	リクエストの ID。X-Request-Id レスポンスヘッダーにも同じ値が入ります

処理の分岐には error.code を使ってください。HTTP ステータスは意外な値になることがあります。USAGE_EXCEEDED と RATE_LIMITED は、どちらもステータス 500 で返ります。

エラーコード

コード	ステータス	意味	再試行
BAD_REQUEST	400	フィールドが無効、API キーが未知、または署名付き URL の署名が間違っている	しません。リクエストを修正してください
FETCH_IMAGE_ERROR	400	Bannerify が画像をダウンロードまたは読み込みできなかった	画像の URL を修正したあと
FORBIDDEN	403	ワークスペースのプランに、Free プランや Automate プランでの s3Config のような機能が含まれていない	しません。フィールドを削除するか、プランを変更してください
NOT_FOUND	404	テンプレートが存在しない	しません。テンプレート ID を修正してください
USAGE_EXCEEDED	500	ワークスペースが 1 日または 1 か月の生成上限に達した	上限がリセットされたあと、またはアップグレードしたあと
RATE_LIMITED	500	API キーが、createImage または署名付き URL に、リクエストを送りすぎた	メッセージに書かれたリセット時刻のあと
TOO_MANY_REQUESTS	400	API キーが、PDF または保存済みファイルのリクエストを送りすぎた	メッセージに書かれたリセット時刻のあと
INTERNAL_SERVER_ERROR	500	リクエストの処理中に何かが失敗した	します。短い間隔をあけて数回

レンダリングに失敗しても、クォータは消費されません。

API に UNAUTHORIZED コードはありません。未知の API キーは BAD_REQUEST を返します。

よくある問題

問題	対処
レンダリングエラーではなく、INTERNAL_SERVER_ERROR でリクエストが失敗する	Content-Type: application/json ヘッダーと、有効な JSON ボディを送ってください。ヘッダーがない、JSON が不正、ボディが空の場合は、このコードで失敗します
modifications の項目の値が変わらない	存在しないレイヤー名は、エラーなしで無視されます。Modifications でスペルを確認してください
format が検証に失敗する	小文字で png、jpeg、webp を使ってください。jpg、JPEG、svg は無効です
大きなテンプレートのレンダリングに時間がかかる	API はリクエストを待たせたままレンダリングします。HTTP クライアントのタイムアウトを延ばしてください。SDK の既定の待機時間は 60 秒です
src の URL の画像が失敗する	高速なホストにある小さいファイルを使ってください。詳しくは FETCH_IMAGE_ERROR を参照してください
JPEG や WebP の出力がぼやける	quality を上げてください。既定値は 90 で、png では無視されます
同じリクエストを繰り返して上限に達する	結果を保存して再利用するか、キャッシュから最長 7 日間返される署名付き URLを使ってください

サポートを受ける

原因がわからない場合は、an@bannerify.co にご連絡いただくか、Discord でお尋ねください。エラーレスポンス全体、特に requestId を含めてください。