API version v1

PrizeNest Developer Documentation

Signed server-to-server purchase and refund events for approved partners. API keys stay separate in the partner dashboard.

Manage API Keys

Errors

Stable error codes with plain-language retry guidance.

Partner API errors return JSON with success false and a stable code. Authentication, signature, scope, partner status, validation, idempotency, funding/rule, refund, and rate-limit errors are logged for partner and admin review.

Error shape

{
  "success": false,
  "error": {
    "code": "INVALID_SIGNATURE",
    "message": "Invalid request signature."
  }
}

Reference

Code	HTTP	Meaning	How to fix	Retry
INVALID_API_KEY	401	Missing, unknown, malformed, or secret-less key.	Fix credentials before retrying.	No
CREDENTIAL_REVOKED	403	The credential was revoked.	Create or rotate a credential.	No
CREDENTIAL_EXPIRED	403	The credential expired.	Generate a new credential.	No
FORBIDDEN_SCOPE	403	The key lacks the required scope.	Use a key with the endpoint scope.	No
MISSING_SIGNATURE	401	X-PrizeNest-Signature is absent.	Send a valid signature header.	No
INVALID_SIGNATURE	401	The HMAC digest does not match.	Check path, body hash, timestamp, and secret.	No
TIMESTAMP_EXPIRED	401	The timestamp is outside the allowed clock window.	Sync clocks and retry promptly.	Yes
INVALID_REQUEST	400	JSON, schema, identifier, or forbidden field validation failed.	Correct the payload.	No
IDEMPOTENCY_CONFLICT	409	A key or event was reused with different data.	Use stable keys only for identical retries.	No
DUPLICATE_ORDER	409	A purchase order was already received with different data.	Inspect original event.	No
NO_ACTIVE_REWARD_RULE	422	No active rule matched the integration and mode.	Create or enable a rule.	No
ORDER_NOT_QUALIFYING	422	The purchase did not meet rule criteria.	Adjust rule or order data.	No
PARTNER_INACTIVE	403	The partner is not approved or active for API rewards.	Complete review and activation.	No
TEST_MODE_DISABLED	403	The partner disabled TEST mode.	Re-enable TEST mode or use LIVE when authorized.	No
ORDER_NOT_FOUND	404	A refund referenced an unknown order reward.	Check externalOrderId and source integration.	No
INVALID_REFUND	422	The reward state cannot be automatically refunded.	Use admin review.	No
RATE_LIMITED	429	Too many requests for the credential/partner/IP window.	Wait before retrying.	Yes

Rate limits

Common signature mistakes

Signing a pretty-printed body but sending minified JSON.
Including query strings instead of only the pathname.
Using lowercase method text instead of uppercase POST.
Using a stale timestamp outside the allowed window.
Putting the raw secret in the public API key header.