處理錯誤

請求失敗時，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 金鑰未知，或簽署網址的簽章錯誤	否。請修正請求
FETCH_IMAGE_ERROR	400	Bannerify 無法下載或讀取圖片	修正圖片網址之後
FORBIDDEN	403	工作區的方案不包含該功能，例如 Free 或 Automate 方案的 s3Config	否。請移除該欄位或變更方案
NOT_FOUND	404	範本不存在	否。請修正範本 ID
USAGE_EXCEEDED	500	工作區已達到每日或每月的生成上限	上限重設之後，或升級之後
RATE_LIMITED	500	API 金鑰傳送了過多的 createImage 或簽署網址請求	訊息中的重設時間之後
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 網址的圖片失敗	請使用放在高速主機上的較小檔案，並參閱 FETCH_IMAGE_ERROR
JPEG 或 WebP 輸出看起來模糊	請調高 quality。預設值是 90，png 會忽略這個參數
重複的請求達到上限	請把結果儲存下來重複使用，或使用簽署網址，快取最多可以提供它 7 天

取得協助

如果找不到原因，請寫信給 an@bannerify.co，或到 Discord 詢問。請附上完整的錯誤回應，尤其是 requestId。