標準エラーコードとJSON形式
SmallPict APIの公式エラーコード一覧、JSONエラー構造、HTTPステータスマッピング。
SmallPictのエラーレスポンスは、すべて機械可読な構造化JSONエンベロープで返されます。
標準エラーJSON構造
JSON
{ "error": { "code": "QUOTA_EXCEEDED", "message": "Monthly image processing quota limit reached for your plan.", "details": { "current_bytes": 10737418240, "quota_bytes": 10737418240, "reset_at": "2026-09-01T00:00:00Z" } }}エラーコード一覧リファレンス
| HTTPステータス | エラーコード (Enum) | SDK例外クラス | エラーの詳細内容 |
|---|---|---|---|
| 400 | VALIDATION_FAILED | ValidationError | リクエスト形式が不正、または必須パラメータが不足 |
| 400 | FILE_TOO_LARGE | FileTooLargeError | 画像サイズがプランの上限を超過 |
| 400 | UNSUPPORTED_FORMAT | UnsupportedFormatError | サポートされていない画像フォーマット |
| 401 | UNAUTHORIZED | AuthenticationError | APIキー、タイムスタンプ、または署名が無効 |
| 401 | ERR_TIMESTAMP_DRIFT | AuthenticationError | クライアント時刻が許容値（±300秒）を超過 |
| 402 | QUOTA_EXCEEDED | QuotaExceededError | 当月の画像処理クォータが上限に到達 |
| 402 | OVERAGE_EXCEEDED | QuotaExceededError | プランの超過猶予上限を超過 |
| 403 | FORBIDDEN | PermissionDeniedError | キーが無効化されているかアカウントが停止中 |
| 403 | KEY_SCOPE_MISMATCH | ScopeMismatchError | 呼び出したAPIとキーのスコープが不一致 |
| 404 | NOT_FOUND | NotFoundError | 指定された job_id やリソースが存在しない |
| 429 | RATE_LIMIT_EXCEEDED | RateLimitError | 短期間のリクエスト過多。Retry-After に従ってください |
| 500 | INTERNAL_ERROR | ServerError | サーバー内部で予期しないエラーが発生 |
| 502 | CDN_UPSTREAM_ERROR | CdnError | SmallPict CDNパージまたは同期に失敗 |
SDKの耐障害性とエラーハンドリング
公式SDKはこれらのJSONエラーを言語ごとの型安全な例外クラスに自動マッピングし、一時的な 429 や 5xx エラーに対してジッター付き指数バックオフによる自動再試行を実行します。