Guides
Error Handling
How to handle API errors gracefully in your integration.
All OnePath API errors follow a consistent structure:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "externalId is required",
"details": [
{ "field": "externalId", "issue": "required" }
]
}
}Handling by Status Code
401 — Unauthorized
Your API key is invalid, expired, or the consent token has expired.
try {
const user = await onepath.users.onboard({ ... });
} catch (err) {
if (err instanceof OnepathAuthError) {
// Refresh your consent token and retry
const newToken = await generateConsentToken(userId);
// retry with newToken
}
}429 — Rate Limited
You've exceeded 100 requests/minute. Respect the Retry-After header.
} catch (err) {
if (err instanceof OnepathRateLimitError) {
const retryAfter = err.retryAfter; // seconds
await sleep(retryAfter * 1000);
// retry
}
}5xx — Server Errors
Safe to retry with exponential backoff. Use jitter to avoid thundering herds.
async function withRetry<T>(fn: () => Promise<T>, maxAttempts = 3): Promise<T> {
for (let attempt = 0; attempt < maxAttempts; attempt++) {
try {
return await fn();
} catch (err) {
if (!(err instanceof OnepathServerError) || attempt === maxAttempts - 1) throw err;
await sleep(Math.pow(2, attempt) * 1000 + Math.random() * 500);
}
}
throw new Error("Max retries exceeded");
}