Error Handling

When something goes wrong, PayMongo returns a structured error response instead of a generic failure. Every error follows the same shape — a predictable format you can parse, log, and act on consistently across your entire integration.

This page covers how PayMongo structures error responses, the types of errors you'll encounter, and how to handle them in code. For the complete list of error codes and what each one means, see Error Codes in the API Reference.

Error response structure

Every error response from the PayMongo API follows the same top-level structure.

"errors": [
    {
      "code": "parameter_invalid",
      "detail": "amount must be at least 2000.",
      "source": {
        "pointer": "attributes.amount"
      }
    }
 ]

PayMongo may return more than one error object in the errors array — for example, when multiple required fields are missing in a single request. Always iterate over the full array rather than reading only the first entry.

Error types

PayMongo errors fall into three broad categories.

Validation errors occur when a request is malformed or missing required fields. These are always your integration's responsibility to handle — check the source.pointer field to identify exactly which parameter needs fixing before retrying.

Authentication errors occur when your API key is missing, invalid, or being used in the wrong environment — for example, a test key used against a live resource. These should never reach production if your integration is configured correctly.

Processing errors occur when a request is well-formed but cannot be completed — a card is declined, a payment method is unavailable, or a resource has already reached a terminal state. These require a response from your integration, such as prompting the customer to try a different payment method.

Handling errors in code

Check the HTTP status code first, then inspect the errors array for specifics.

const response = await fetch("https://api.paymongo.com/v1/payment_intents", {
  method: "POST",
  headers: {
    Authorization: `Basic ${btoa(apiKey + ":")}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
});

if (!response.ok) {
  const { errors } = await response.json();

  for (const error of errors) {
    console.error(`[${error.code}] ${error.detail}`);

    if (error.code === "card_declined") {
      // Prompt customer to use a different payment method
    }

    if (error.code === "parameter_invalid") {
      // Fix the request before retrying
    }
  }
}

Match on code — not detail. The detail field is intended for human readers and may change. The code field is stable and safe to use in logic.