Standard Error Codes & Envelopes
Error response format, error codes, and HTTP status codes of the SmallPict API.
Every error response uses the same JSON structure with a machine-readable error code.
Error response format
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" } }}Error codes
| 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 | SmallPict CDN cache purge or origin sync failure. Retry the request. |
Error handling in the SDKs
The SDKs turn these errors into typed exceptions for each language and retry 429 and 5xx responses with exponential backoff and jitter.