Handle API errors

All partner API errors use the same JSON envelope:

{
	"error": {
		"code": "idempotency_conflict",
		"message": "This leadId is already attached to different claim details"
	}
}

Error reference

HTTP	Code	Meaning	Action
`400`	`invalid_json`	The request body is not valid UTF-8 JSON.	Correct the JSON before retrying.
`400`	`invalid_request`	A field or event-feed query failed validation.	Send only the documented fields and constraints.
`401`	`unauthorized`	The bearer key is missing, malformed, revoked, or inactive.	Replace it with an active key.
`404`	`not_found`	The claim is invalid or not visible to this access grant.	Check the claim ID and authenticated grant.
`409`	`idempotency_conflict`	The `leadId` already has different claim details.	Use the original details or a new lead ID.
`409`	`credit_budget_exceeded`	New claims would exceed the access grant’s total credit budget.	Ask an administrator to increase the budget.
`409`	`claim_limit_exceeded`	The access grant has allocated 100,000 unique claims.	Ask an administrator for a new or expanded grant.
`413`	`request_too_large`	The request body exceeds 16 KiB.	Reduce the body before retrying.
`415`	`unsupported_media_type`	The request does not use `application/json`.	Set the correct `Content-Type`.
`422`	`credit_amount_exceeds_limit`	The whole-credit amount exceeds the per-claim limit.	Lower the amount to the limit shown on the API access page.
`429`	`rate_limited`	The API key exceeded 600 requests in one minute.	Wait for `Retry-After`, then retry.
`500`	`internal_error`	Sparkles could not complete the request.	Retry with exponential backoff.

All successful and error responses include Cache-Control: private, no-store.

Retry policy

Retry network failures and HTTP 500 responses with exponential backoff and jitter. For HTTP 429, wait at least the number of seconds in Retry-After. Do not automatically retry validation, authorization, conflict, size, or media-type errors without changing the request or access configuration. Creating a credit claim is safe to retry because leadId is its idempotency key. A byte-for-byte identical JSON body is not required, but the normalized email, variant, and credit amount must match the original claim details.

Example retry decision

export function shouldRetry(status: number) {
	return status === 429 || status >= 500;
}

Cap automated retries, record the final error code, and preserve the original leadId across every create-claim attempt.

Get started

Integration guides

API reference

Error reference

Retry policy

Example retry decision

​Error reference

​Retry policy

​Example retry decision

Error reference

Retry policy

Example retry decision