Errors

When something goes wrong, DoorPay returns a clear error response with an HTTP status code, a human-readable message, and (for validation errors) a field-by-field breakdown of what's wrong.

Error Response Format

All error responses follow one of two formats depending on the error type:

Standard Error

Standard error response

{
  "success": false,
  "message": "Order not found: DP-INVALID",
  "data": null,
  "timestamp": "2026-03-13T10:00:00Z"
}

Validation Error (400)

When your request body fails validation, you get a detailed breakdown:

Validation error response

{
  "message": "Validation failed",
  "status": 400,
  "error": "Bad Request",
  "timestamp": "2026-03-13T10:00:00Z",
  "validationErrors": {
    "amount": "must be greater than or equal to 5.0",
    "buyerEmail": "must be a valid email address",
    "buyerPhone": "must match \"^\\+91[0-9]{10}$\"",
    "description": "must not be blank"
  }
}

HTTP Status Codes

Code	Meaning	When You'll See It
`200`	OK	Request succeeded. Response contains the data you asked for.
`201`	Created	Order successfully created.
`400`	Bad Request	Validation failed (missing fields, invalid amount, wrong phone format), or you tried to do something the order's current status doesn't allow (e.g., deliver an unpaid order).
`401`	Unauthorized	Missing or invalid API key/secret. Double-check your X-API-Key and X-API-Secret headers.
`403`	Forbidden	Your merchant account is not approved or not active, the order belongs to a different merchant, or your Origin is not whitelisted.
`404`	Not Found	The order number you specified doesn't exist.
`408`	Request Timeout	Payment session expired. The buyer took too long to complete payment.
`429`	Too Many Requests	Rate limit exceeded. Slow down and retry after a short delay.
`500`	Internal Server Error	Something went wrong on our end. Retry with exponential backoff. If it persists, contact support.
`502`	Bad Gateway	Payment gateway (UPI provider) is temporarily unavailable. Retry after a few minutes.

Common Errors & How to Fix Them

"must be greater than or equal to 5.0" (amount)

The minimum order amount is ₹5.00 and maximum is ₹10,000.00. Make sure your amount is within this range.

"must match \"^\\+91[0-9]{10}$\"" (buyerPhone)

Phone number must be in +91XXXXXXXXXX format — the country code +91 followed by exactly 10 digits. No spaces, dashes, or parentheses.

"Cannot mark as delivered. Order must be in PAID status."

You can only deliver an order after the buyer has paid. Check the order status first with GET /orders/{id}. Wait for the PAYMENT_SUCCESS webhook before calling deliver.

"Cannot cancel. Order must be in ACCEPTED status."

You can only cancel an order before the buyer pays. Once paid, the order must go through the delivery → completion flow.

"Access denied: this order does not belong to your merchant account"

You're trying to access an order that was created by a different merchant. Each merchant can only see their own orders.

"Merchant must be approved first"

Your merchant account hasn't been approved yet. Complete the KYC process and wait for admin approval before using the API.

Error Handling Tips

Check the success field

Every response has a "success" boolean. Check this first before trying to read the data field.

Read the message

The message field tells you exactly what went wrong in plain English. It's safe to log these messages.

Use validationErrors for forms

When you get a 400 with validationErrors, each key is a field name and the value is the error. Use these to show inline errors in your UI.

Retry on 500 and 502

Server errors and gateway errors are usually temporary. Retry with exponential backoff (1s, 2s, 4s, 8s...).

Don't retry on 400, 401, 403, 404

These are client errors — retrying won't help. Fix the request and try again.