Standard Error Codes & Envelopes

Authoritative error code mapping, JSON structure, and HTTP status codes for the SmallPict API.

Standard Error Codes & Envelopes

All SmallPict error responses return a standardized JSON envelope with typed machine-readable error codes.

📦 Standard Error JSON Structure

{
  "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"
    }
  }
}

📋 Complete Error Code Reference

HTTP Status	ErrorCode Enum	Exception Type	Description
400	`VALIDATION_FAILED`	`ValidationError`	Request payload failed schema validation or missing required fields.
400	`FILE_TOO_LARGE`	`FileTooLargeError`	Uploaded image exceeds single-file upload size limit for current plan tier.
400	`UNSUPPORTED_FORMAT`	`UnsupportedFormatError`	The provided file is not a supported image format.
401	`UNAUTHORIZED`	`AuthenticationError`	Missing or invalid API key, timestamp, or HMAC-SHA256 signature.
401	`ERR_TIMESTAMP_DRIFT`	`AuthenticationError`	Client timestamp drifted beyond the allowed ±300s window.
402	`QUOTA_EXCEEDED`	`QuotaExceededError`	Monthly account processing quota exhausted.
402	`OVERAGE_EXCEEDED`	`QuotaExceededError`	Plan overage buffer limit exceeded.
403	`FORBIDDEN`	`PermissionDeniedError`	The API key is revoked or account is suspended.
403	`KEY_SCOPE_MISMATCH`	`ScopeMismatchError`	Using a WordPress scoped key (`sp_wp_...`) on an SDK endpoint or vice versa.
404	`NOT_FOUND`	`NotFoundError`	The requested resource or conversion `job_id` does not exist.
429	`RATE_LIMIT_EXCEEDED`	`RateLimitError`	Too many requests in a short duration. Follow the `Retry-After` header.
500	`INTERNAL_ERROR`	`ServerError`	An unhandled error occurred on the server. Details are logged securely.
502	`CDN_UPSTREAM_ERROR`	`CdnError`	Cloudflare Edge CDN purge or origin sync failure.

🛡️ SDK Resilience & Error Handling

Official SmallPict SDKs automatically wrap these JSON errors into language-native typed exceptions and automatically retry transient 429 and 5xx errors using exponential backoff with jitter.