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
The API always returns an error object in the response body for non-2xx responses. Check the HTTP status code first, then inspect error.type and error.code:
curl -X POST https://api.plexypay.com/v2/payments \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"amount": 5000, "currency": "USD", "payment_method": "pm_card_visa"}'Example error response:
{
"error": {
"type": "card_error",
"code": "card_declined",
"message": "Your card was declined.",
"request_id": "req_abc123"
}
}| HTTP status | error.type | Action |
|---|---|---|
402 | card_error | Show error.message to the customer |
400 | invalid_request_error | Fix the request parameters |
401 | authentication_error | Check your API key configuration |
500–503 | api_error | Retry with exponential backoff |
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." |