Error Codes
API error types and codes
Error Codes
Understand and handle errors returned by the Plexy API.
Error structure
{
"error": {
"type": "invalid_request_error",
"code": "parameter_missing",
"message": "Missing required parameter: amount",
"param": "amount",
"request_id": "req_abc123"
}
}| Field | Description |
|---|---|
type | Error category |
code | Specific error code |
message | Human-readable description |
param | Parameter that caused error (if applicable) |
request_id | Unique request identifier |
Error types
api_error
Server-side errors. Usually temporary - retry with backoff.
| Code | Description |
|---|---|
api_error | General API error |
invalid_request_error
Client-side request errors. Fix the request and retry.
| Code | Description |
|---|---|
parameter_missing | Required parameter not provided |
parameter_invalid | Parameter value is invalid |
parameter_unknown | Unrecognized parameter |
resource_missing | Referenced resource doesn't exist |
idempotency_error | Idempotency key reused with different params |
authentication_error
API key or authentication problems.
| Code | Description |
|---|---|
api_key_invalid | Invalid API key |
api_key_expired | API key has expired |
api_key_revoked | API key was revoked |
card_error
Payment card issues. Display message to customer.
| Code | Description |
|---|---|
card_declined | Card was declined |
expired_card | Card has expired |
incorrect_cvc | CVC is incorrect |
incorrect_number | Card number is incorrect |
insufficient_funds | Card has insufficient funds |
processing_error | Error processing card |
Handling errors
try {
const payment = await plexy.payments.create({ /* ... */ });
} catch (error) {
switch (error.type) {
case 'card_error':
// Show message to customer
displayError(error.message);
break;
case 'invalid_request_error':
// Log and fix integration
console.error('Integration error:', error.code, error.param);
break;
case 'authentication_error':
// Check API key configuration
console.error('Auth error:', error.code);
break;
case 'api_error':
// Retry with exponential backoff
await retryWithBackoff(() => createPayment());
break;
}
}Customer-facing messages
Map error codes to user-friendly messages:
| Code | Customer Message |
|---|---|
card_declined | "Your card was declined. Please try a different card." |
expired_card | "Your card has expired. Please use a valid card." |
incorrect_cvc | "The security code is incorrect. Please check and try again." |
insufficient_funds | "Your card has insufficient funds. Please try a different card." |
processing_error | "An error occurred processing your card. Please try again." |