Errors & Status Codes — SyncNexa Docs

SyncNexa uses standard HTTP status codes to indicate the success or failure of API requests. Error responses return a JSON object with structured diagnostic information.

Error Response Format

error-response.jsonjson

1 {
2   "error": {
3     "code": "INVALID_REQUEST_PARAMETERS",
4     "message": "The field 'requiredClaims' must be a non-empty array of valid strings.",
5     "param": "requiredClaims",
6     "docUrl": "https://docs.syncnexa.co/api/verification-api#create-session"
7   }
8 }

HTTP Status Codes

Status Code	Meaning	Description
`200 OK`	Success	The request completed successfully.
`201 Created`	Resource Created	A new application, API key, or verification session was created.
`400 Bad Request`	Invalid Request	Missing required parameters or malformed JSON payload.
`401 Unauthorized`	Authentication Failed	Missing, invalid, or revoked API key.
`403 Forbidden`	Permission Denied	API key lacks permission for the requested environment or resource.
`404 Not Found`	Resource Missing	The requested application, key, session, or webhook was not found.
`409 Conflict`	Resource Conflict	An application or redirect URI with this name/value already exists.
`422 Unprocessable Entity`	Validation Error	Schema validation failed for one or more fields.
`429 Too Many Requests`	Rate Limit Exceeded	Too many requests sent within the active rate limit window.
`500 Internal Error`	Server Error	An unexpected error occurred on SyncNexa servers.

SyncNexa Error Codes

Error Code	HTTP Status	Description
`UNAUTHORIZED`	401	API key is missing or invalid in the Authorization header.
`KEY_REVOKED`	401	The provided API key has been explicitly revoked.
`ENVIRONMENT_MISMATCH`	403	Sandbox keys cannot be used to verify live production sessions.
`APP_NOT_FOUND`	404	Application UUID does not exist or does not belong to your organization.
`SESSION_EXPIRED`	410	Verification session has elapsed its time-to-live window.
`PROOF_INVALID`	422	Zero-knowledge proof failed cryptographic verification against issuer public key.
`RATE_LIMIT_EXCEEDED`	429	Too many requests; back off and retry.

Handling Rate Limits & Retries

When handling HTTP 429 or HTTP 5xx responses, implement exponential backoff with randomized jitter to prevent thundering herd problems:

backoff.tstypescript

1 async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {
2   for (let attempt = 0; attempt < maxRetries; attempt++) {
3     try {
4       const response = await fetch(url, options);
5       if (response.status !== 429 && response.status < 500) {
6         return response;
7       }
8     } catch (err) {
9       if (attempt === maxRetries - 1) throw err;
10     }
11     const delay = Math.pow(2, attempt) * 1000 + Math.random() * 500;
12     await new Promise((resolve) => setTimeout(resolve, delay));
13   }
14 }

Was this page helpful?

1	{
2	"error": {
3	"code": "INVALID_REQUEST_PARAMETERS",
4	"message": "The field 'requiredClaims' must be a non-empty array of valid strings.",
5	"param": "requiredClaims",
6	"docUrl": "https://docs.syncnexa.co/api/verification-api#create-session"
7	}
8	}

1	async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {
2	for (let attempt = 0; attempt < maxRetries; attempt++) {
3	try {
4	const response = await fetch(url, options);
5	if (response.status !== 429 && response.status < 500) {
6	return response;
7	}
8	} catch (err) {
9	if (attempt === maxRetries - 1) throw err;
10	}
11	const delay = Math.pow(2, attempt) * 1000 + Math.random() * 500;
12	await new Promise((resolve) => setTimeout(resolve, delay));
13	}
14	}