Error Codes

The Mesta API uses standard HTTP status codes to indicate the success or failure of requests. All error responses share one envelope.

Error Response Format

Every error response has this shape:

{
  "error": {
    "CODE": "VALIDATION_FAILED",
    "MESSAGE": "Failed to validate given entity",
    "DETAILS": [
      "senderId must be a UUID",
      "acceptedQuoteId should not be empty"
    ]
  },
  "requestId": 177021679
}

HTTP Status Codes

Validation Errors

When request validation fails, the response is 400 with CODE: VALIDATION_FAILED and one message per failed constraint in DETAILS. Nested fields are dot-prefixed with their parent property, and array items include their index:

{
  "error": {
    "CODE": "VALIDATION_FAILED",
    "MESSAGE": "Failed to validate given entity",
    "DETAILS": [
      "senderId must be a UUID",
      "acceptedQuoteId should not be empty",
      "purpose must be one of the following values: payroll, operational_expense, vendor_payment, ...",
      "addresses.0.country must be one of the following values: US, GB, DE, ..."
    ]
  },
  "requestId": 177021679
}

Common Error Codes

Platform-wide codes you can expect on any endpoint:

Business Logic Errors

These occur when the request is well-formed but cannot be processed. All return 400.

Tips for Error Handling

1. Branch on error.CODE, never on error.MESSAGE — message copy can change without notice.
2. Read error.DETAILS for the specific field failures behind a VALIDATION_FAILED.
3. Log requestId on every failure and include it in support requests.
4. Implement retry logic with exponential backoff for 429 and 500 responses. Honour the Retry-After header on 429s.
5. Do not retry 400, 401, 403, or 410 — these require fixing the request.
6. Use the validation rules endpoints before creating senders and beneficiaries so your payload meets the country-specific requirements.