Error Handling

How to handle errors from the Pymstr API. All errors follow a consistent format.

Error Format#

Standard errors return a JSON object with statusCode, message, and error.

Standard Error

{
  "statusCode": 400,
  "message": "Error description",
  "error": "Bad Request"
}

Validation Errors#

Validation errors include an additional errors array with the specific field paths and messages.

Validation Error

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request",
  "errors": [
    {
      "path": [
        "amount"
      ],
      "message": "amount must be a string with 0–2 decimal places"
    }
  ]
}

HTTP Status Codes#

Code	Meaning
`200`	Success
`201`	Created
`204`	No Content (successful deletion/action)
`400`	Bad Request (validation or authorization error)
`401`	Unauthorized (missing or invalid authentication)
`403`	Forbidden (insufficient permissions)
`404`	Not Found
`409`	Conflict (e.g., externalId in use by an ACTIVE/PROCESSING/SUCCESSFUL payment or payout, API key limit reached)
`429`	Too Many Requests (rate limit exceeded)
`500`	Internal Server Error
`502`	Bad Gateway (upstream error)
`504`	Gateway Timeout

Common Mistakes#

Invalid amount format

The amount field must be a string with 0, 1, or 2 decimal places.

100.00 "100.123""100" "100.5" "100.00" "0.01"

Duplicate externalId

Each externalId must be unique per merchant. Reusing one returns 409 Conflict. Use order IDs or UUIDs to ensure uniqueness.

Cancelling a non-ACTIVE payment or payout

Only payments and payouts with status ACTIVE can be cancelled (DELETE /v1/payments/:id or /v1/payouts/:id). Trying to cancel a PROCESSING or completed one returns 400 Bad Request.

Split amounts don't add up

When using split payments, merchantAmount + sum(sellers) must equal amount. A mismatch returns a validation error.

Error handling best practice

Always check the HTTP status code first, then parse the JSON body for details. Use the errors array (when present) to show field-specific feedback to your users.