Error Reference

When something goes wrong, the Pro Clubs Studio API returns a consistent error envelope. This page catalogues every error code, its HTTP status, and how to resolve it.

Error envelope format

All error responses follow the same JSON structure. The success field is always false and the error object contains the details:

{
  "success": false,
  "data": null,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Human-readable explanation of what went wrong.",
    "request_id": "req_abc123",
    "docs_url": "https://platform.proclubsstudio.com/docs/errors/INVALID_REQUEST"
  }
}

Field	Type	Description
`error.code`	`string`	Machine-readable error code. Use this for programmatic error handling.
`error.message`	`string`	Human-readable description. Suitable for logging but not for end-user display.
`error.request_id`	`string`	Unique request identifier. Include this when contacting support.
`error.docs_url`	`string?`	Optional link to this documentation for more details on the error.

Error catalog

Click any error code to see detailed causes and remediation steps.

HTTP	Error Code	Description
401	INVALID_API_KEY	The API key is missing, malformed, or has been revoked. Check the X-API-Key header.
403	PARTNER_SUSPENDED	The partner account associated with this API key has been suspended. Contact support.
400	INVALID_REQUEST	The request body failed validation. Check required fields, types, and value constraints.
404	IMAGE_NOT_FOUND	The image_id does not exist or does not belong to your partner account.
402	INSUFFICIENT_CREDITS	Your account does not have enough credits to process this request. Top up or wait for refunds.
422	UNSUPPORTED_IMAGE_SOURCE	The source_image_url is unreachable, returns an unsupported format, or exceeds the size limit.
429	RATE_LIMIT_EXCEEDED	Too many requests in the current window. Respect the Retry-After header before retrying.
409	IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_PAYLOAD	The same Idempotency-Key was used with a different request body. Use a new key for different requests.
200	IMAGE_PROCESSING_FAILED	The image request reached a terminal failed state. This is a resource-level failure (the request exists, but generation failed). Returned inside the data object, not as an HTTP error.
200	PROCESSING_TIMEOUT	Image processing did not complete within the allowed time (5 minutes). The reserved credit has been refunded.
500	INTERNAL_ERROR	An unexpected error occurred on our side. Retry with exponential backoff. If persistent, contact support.

Rate limit headers

Every response includes rate limit information. When you receive a 429 response, use these headers to implement proper backoff:

Header	Example	Description
`X-RateLimit-Limit`	`30`	Maximum requests allowed per minute for your tier.
`X-RateLimit-Remaining`	`0`	Requests remaining in the current window.
`X-RateLimit-Reset`	`1740000020`	Unix timestamp when the rate limit window resets.
`Retry-After`	`20`	Seconds until you can retry. Only present on `429` responses.

Tip: Rate limits are per partner, not per IP address. Distributing requests across multiple servers does not increase your limit. Monitor the X-RateLimit-Remaining header and throttle preemptively.