{
"error": {
"type": "invalid_request",
"code": "missing_required_field",
"message": "title is required",
"param": "title",
"requestId": "req_550e8400-e29b-41d4-a716-446655440000"
}
}
| Field | Description |
|---|---|
type | High-level error category (see below) |
code | Machine-readable error code within the type |
message | Human-readable description |
param | The field that caused the error, if applicable |
requestId | Unique ID for this request — include this when contacting support |
Error types
| Type | HTTP status | When it happens |
|---|---|---|
invalid_request | 400 | Missing field, bad format, or invalid value |
authentication | 401 | Missing, invalid, or revoked API key |
permission | 403 | API key lacks the required scope |
not_found | 404 | The requested resource doesn’t exist |
conflict | 409 | Idempotency key reused with different body |
rate_limited | 429 | Too many requests — back off and retry |
server | 500 | Unexpected server error |
Handling errors
Check the HTTP status code first, then branch onerror.type for programmatic handling.
try {
const session = await client.checkoutSessions.create({ ... });
} catch (e) {
if (e instanceof CheckoutApiError) {
switch (e.type) {
case "authentication":
// Prompt user to reconfigure their API key
break;
case "rate_limited":
// Implement exponential backoff
await sleep(e.retryAfter ?? 1000);
break;
case "invalid_request":
// Surface e.param and e.message to the user
break;
}
}
}