Error Codes

The Mesta API uses standard HTTP status codes to indicate the success or failure of requests. All error responses follow a consistent format.

HTTP Status Codes

Status Code	Meaning	Description
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`400`	Bad Request	Invalid request body or parameters. Check the `message` field for details.
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Insufficient permissions for the requested operation
`404`	Not Found	Resource not found
`409`	Conflict	Resource already exists or state conflict
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Unexpected server error

Error Response Format

All error responses follow this structure:

{
  "statusCode": 400,
  "message": [
    "firstName must be a string",
    "email must be a valid email address"
  ],
  "error": "Bad Request"
}

Field	Type	Description
`statusCode`	number	HTTP status code
`message`	string or string[]	Error description. Validation errors return an array of messages.
`error`	string	Human-readable error category

Validation Errors

When request validation fails (400 Bad Request), the message field contains an array of specific validation failures:

{
  "statusCode": 400,
  "message": [
    "senderId must be a UUID",
    "acceptedQuoteId should not be empty",
    "purpose must be one of the following values: PAYROLL, VENDOR_PAYMENT, ..."
  ],
  "error": "Bad Request"
}

Business Logic Errors

These errors occur when the request is valid but cannot be processed due to business rules:

Error	Status	Description
Quote expired	400	The quote has expired. Create a new quote.
Sender not verified	400	The sender must be verified before creating orders.
Beneficiary not verified	400	The beneficiary must be verified before creating orders.
Payment method not approved	400	The payment method must be in `approved` status.
Insufficient balance	400	Insufficient funds in the merchant account.
Duplicate order	409	An order with this quote ID already exists.
Order cannot be cancelled	400	The order is in a state that does not allow cancellation.

Tips for Error Handling

Always check the message array for specific validation failures when receiving a 400 error.
Implement retry logic with exponential backoff for 429 and 500 errors.
Do not retry 400, 401, or 403 errors — these require fixing the request.
Use validation rules endpoints before creating entities to ensure your data meets requirements.