CWM Pay API Error Codes: Reference and Handling Guide

Reference for all CWM Pay API error codes, HTTP status codes, and recommended handling strategies for authentication, payment, and validation errors.

When a request to the CWM Pay API fails, the response body contains a JSON error object with a code, message, and type that describe exactly what went wrong. Use this page to look up any error you encounter, understand its cause, and apply the right fix or retry strategy in your integration.

Error Response Format

Every failed request returns the same error envelope, regardless of the error type:

{
  "error": {
    "type": "card_error",
    "code": "card_declined",
    "message": "Your card was declined.",
    "param": null,
    "request_id": "req_abc123"
  }
}

Field	Description
type	The broad category of the error (see Error Types below).
code	A machine-readable string identifying the specific error.
message	A human-readable description of what went wrong.
param	The request parameter that caused the error, if applicable; otherwise null.
request_id	A unique identifier for this request. Include this when contacting support.

Error Types

Use the type field to determine the correct handling strategy at a high level before inspecting the specific code.

Type	Description
api_error	Something went wrong on CWM Pay’s end. Retry with exponential backoff.
authentication_error	Invalid or missing API key. Check your Authorization header.
card_error	The customer’s card was declined or is invalid.
invalid_request_error	Bad request parameters — check your request body against the API reference.
rate_limit_error	Too many requests. Slow down and retry after a delay.

HTTP Status Codes

CWM Pay uses standard HTTP status codes alongside the JSON error body.

Status	Description
200 OK	Request succeeded.
400 Bad Request	Invalid parameters. Check the error.param field for the offending field name.
401 Unauthorized	Missing or invalid API key. Verify your Authorization: Bearer header.
402 Payment Required	The card was declined. Surface the error.message to the customer.
404 Not Found	The requested resource does not exist. Check the ID in your request path.
409 Conflict	Duplicate request detected. Use idempotency keys to prevent unintended double charges.
422 Unprocessable Entity	The request was valid but could not be processed in its current state.
429 Too Many Requests	Rate limit exceeded. Retry after the value in the Retry-After response header.
500 Internal Server Error	CWM Pay server error. Retry with exponential backoff. If the issue persists, contact [e-mail].

Card Error Codes

When error.type is card_error, use the code field to decide how to respond to your customer.

Code	Recommended Action
card_declined	Generic decline. Ask the customer to try a different card.
insufficient_funds	Card has insufficient funds. Ask the customer to use a different payment method.
expired_card	Card is expired. Ask the customer to update their card details.
incorrect_cvc	CVC is incorrect. Ask the customer to re-enter their security code.
incorrect_zip	Billing ZIP doesn’t match. Ask the customer to verify their billing address.
do_not_honor	Card issuer declined. Ask the customer to contact their bank.
lost_card	Card reported lost. Do not retry — ask the customer to use a different card.
stolen_card	Card reported stolen. Do not retry — ask the customer to use a different card.
fraudulent	Payment flagged as fraudulent. Do not retry this charge.

Authentication Error Codes

When error.type is authentication_error, your API key is missing, malformed, or invalid. These errors always return HTTP 401.

Code	Recommended Action
api_key_missing	No Authorization header was sent. Add Authorization: Bearer YOUR_SECRET_KEY to every request.
api_key_invalid	The key was provided but is not recognized. Verify the key in your dashboard under Settings → API Keys.
api_key_revoked	The key has been revoked. Generate a new key in Settings → API Keys and update your configuration.
api_key_wrong_mode	You used a live key against a test resource, or vice versa. Match your key prefix (sk_live_ or sk_test_) to the environment you’re targeting.

Invalid Request Error Codes

When error.type is invalid_request_error, one or more fields in your request body or URL are incorrect. Check error.param for the name of the offending field.

Code	Recommended Action
parameter_missing	A required field was omitted. Add the field named in error.param to your request.
parameter_invalid	A field was present but its value is not valid (wrong type, out of range, etc.). Check the API reference for allowed values.
resource_not_found	The ID in your request path does not match any existing object. Confirm the ID is correct.
resource_already_exists	You tried to create a resource that already exists (for example, a duplicate customer email). Use the existing resource or provide different values.
amount_too_small	The amount is below the minimum allowed for the currency. Check the minimum charge amount for your currency.
currency_not_supported	The currency value is not supported for your account or region. Check your dashboard for enabled currencies.

Handling Errors in Code

Wrap every API call in error handling logic that inspects error.type and error.code to decide whether to surface a message to the customer, retry the request, or escalate to your team.

JavaScript

try {
  const response = await fetch('https://api.cwmpay.com/v1/payments', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.CWM_SECRET_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ amount: 1000, currency: 'usd' })
  });

  if (!response.ok) {
    const { error } = await response.json();
    console.error(error.code, error.message);

    switch (error.type) {
      case 'card_error':
        // Surface error.message to the customer
        break;
      case 'authentication_error':
        // Check your API key configuration
        break;
      case 'invalid_request_error':
        // Fix your request parameters — check error.param
        break;
      case 'rate_limit_error':
      case 'api_error':
        // Retry with exponential backoff
        break;
      default:
        // Log and investigate
    }
  }
} catch (err) {
  // Network error — retry with backoff
  console.error('Network error:', err.message);
}

Rate Limits

CWM Pay enforces the following request limits per API key:

• Live mode: 100 requests per second
• Test mode: 20 requests per second

When you exceed the limit, the API returns a 429 Too Many Requests response. Check the Retry-After header in the response for the number of seconds to wait before retrying. Implement exponential backoff with jitter in your retry logic to avoid thundering-herd issues during traffic spikes.

Every API error response includes a request_id field (for example, req_abc123). Always include this value when you contact [e-mail] — it allows the CWM Pay support team to locate your exact request and diagnose the issue faster.