Error Handling

This page covers the response status codes the Create Session endpoint can return, the recommended retry strategy, and a debug checklist when the endpoint responds with 401 Invalid Signature or 422 Validation Failed.

Status Codes

Code	Meaning	Retry?
200	Success - session created	-
401	Unauthorized - signature is invalid	No
403	Forbidden - domain not whitelisted for tokenized widget access	No
404	Not Found - partner not found or inactive	No
422	Validation Failed - payload invalid	No
429	Too Many Requests - rate limit exceeded	Yes
500	Internal Server Error	Yes
502	Bad Gateway	Yes
503	Service Unavailable	Yes
504	Gateway Timeout	Yes

⚠️

Do not retry on 401, 404, or 422. These are caused by bad requests on the partner side - retries will keep failing and may cause unnecessary load. Investigate the request payload first.

Retry Strategy

When a retryable status code is returned, use exponential backoff with jitter to avoid thundering-herd retries.

Max 3 attempts, base delay 500 ms.
Formula: min(500 * 2^attempt + random(0..300), 8000) ms.
Approximate intervals: ~500 ms, ~1000 ms, ~2000 ms.
For endpoints with side-effect duplication risk, send an idempotency key or unique request key alongside the retry.

If the final retry attempt still fails, stop, log the final error, and forward the failure to your internal monitoring or alerting system.

Circuit Breaker (Recommended)

To prevent continuously calling the API when failure rate is high, apply a circuit breaker:

Parameter	Recommended value
Rolling window	20 requests
Minimum sample	10 requests
Failure rate threshold	50%
Slow call threshold	> 3 seconds
Slow call rate threshold	60%
Open state duration	30 seconds
Half-open trial	3 requests

OPEN: fail-fast new requests for the open state duration.
HALF_OPEN: only allow a few trial requests through.
CLOSED: restored after 3 consecutive half-open successes.

Authentication Debug Guide

When you receive 401 Invalid Signature, walk through this checklist:

Does the partnerId in the URL exactly match the partnerId used in the canonical string?
Field order: partnerId | user_id | email | name | company_id | candidate_ids_csv?
Field delimiter is |, candidate_id delimiter is ,?
Empty optional fields are preserved as empty strings (not omitted)?
No stray spaces, newlines, or hidden characters in the canonical string before hashing?
secretKey matches the current environment (dev secretKey ≠ prod secretKey)?
candidate_id order in the canonical string matches the array order in the payload?

When you receive 422 Validation Failed:

Required fields present: user.user_id, user.email, user.name, signature?
Valid email format?
Correct user.company and user.candidates structure?

Recommended Debug Log Shape

[DEBUG] partnerId: psikologihub-1024
[DEBUG] canonical: psikologihub-1024|USR-001|[email protected]|John Doe|COMP-001|CND-001,CND-002
[DEBUG] generated_signature: <hex>
[DEBUG] request_signature:   <hex>
[DEBUG] match_signature:     true/false

🚫

Never log the secretKey, full session tokens, or raw signatures. If logs are stored in a shared environment, mask or redact any sensitive content.

Authentication Testing Guide