Errors

This page describes the HTTP status codes and error codes returned by the Mpay API.

Error Response

API responses use the following general structure:

{
  "code": "bad_request",
  "message": "Invalid request parameters",
  "data": null
}

The status in the API result definition corresponds to the HTTP response status code, while code is the application-level error code returned in the JSON response body.

For example:

HTTP 400 Bad Request

with:

{
  "code": "bad_request",
  "message": "Invalid request parameters",
  "data": null
}

HTTP Status Codes and Result Codes

The HTTP status is the transport-level status returned by the server. The code field is the application-level result code in the JSON response body.

Authentication Errors

Authentication errors returned by the HMAC authentication middleware use dedicated authentication codes. They should not be confused with the general business result code unauthorized.

Authentication failures return HTTP 401 and use the following codes:

For example, a missing authentication header returns:

{
  "code": "auth_missing_headers",
  "message": "Missing required signature headers (X-Api-Key/X-Timestamp/X-Nonce/X-Signature)",
  "data": null
}

auth_missing_headers

One or more of the following headers are missing:

X-Api-Key
X-Timestamp
X-Nonce
X-Signature

Make sure all required headers are included in every authenticated request.

auth_invalid_timestamp

The X-Timestamp header cannot be converted to a valid finite numeric value.

X-Timestamp should contain a millisecond Unix timestamp.

auth_timestamp_expired

The request timestamp is outside the allowed time window. The default allowed clock difference is 5 minutes.

If the client and server clocks differ by more than the allowed window, generate a new timestamp and signature before retrying.

auth_invalid_api_key

The API key is invalid because it does not exist or has been disabled.

Check that the correct API key is being used and that it is active.

auth_nonce_reused

The X-Nonce value has already been used for the API key.

Every request must use a new nonce. A UUID is recommended.

The nonce is registered after the signature has been successfully verified, and the default nonce retention period is 5 minutes.

auth_signature_mismatch

The HMAC signature calculated by the server does not match the value supplied in X-Signature.

Check the following:

1. The correct API secret is being used.
2. The HTTP method is correct.
3. The request path is correct and does not include the query string.
4. X-Timestamp is exactly the value used to generate the signature.
5. X-Nonce is exactly the value used to generate the signature.
6. GET query parameters are canonicalized correctly.
7. POST request bodies are canonicalized correctly.
8. HMAC-SHA256 is used to calculate the signature.
9. The resulting signature is encoded as lowercase hexadecimal.

The API secret is used locally by the client to calculate the signature and is never sent as part of an API request.

Internal Authentication Error

If an unexpected error occurs while processing authentication, the authentication middleware returns HTTP 500 with the following application-level code:

{
  "code": "internal_auth_error",
  "message": "Internal auth error",
  "data": null
}

This is different from the general business system error:

{
  "code": "internal_error",
  "message": "...",
  "data": null
}

Both represent server-side errors, but internal_auth_error specifically identifies an unexpected error in the authentication layer.

Handling Errors

Do not retry authentication errors unchanged

For auth_missing_headers, auth_invalid_timestamp, auth_timestamp_expired, auth_invalid_api_key, auth_nonce_reused, and auth_signature_mismatch, correct the underlying problem before sending another request.

When retrying after an authentication-related problem, generate a new timestamp and nonce and calculate a new signature as appropriate.

Handle pending separately from errors

pending uses HTTP 202 and means that the request has been accepted but the operation has not completed yet. It is not a failed request.

For asynchronous operations, use the operation/status mechanism documented by the corresponding API to determine the final result.

Retry server-side failures carefully

too_busy, internal_error, and insufficient_resources indicate server-side conditions. If the endpoint operation is safe to retry, retry with an appropriate backoff strategy. For operations that are not idempotent, make sure the retry cannot create a duplicate operation.

Business Errors

The following result codes are defined for business/API operations:

success
pending
bad_request
unauthorized
insufficient_balance
forbidden
not_found
unsupported
already_exists
canceled
too_busy
internal_error
insufficient_resources

Individual API endpoints may provide additional information in the message and data fields to explain the specific failure. Refer to the corresponding API Reference page for endpoint-specific behavior.

Troubleshooting

When contacting support about an API error, provide:

• The endpoint and HTTP method
• The HTTP status code
• The code value from the response body
• The response message
• The X-Timestamp and X-Nonce from the failing request, when applicable
• A request ID or transaction/operation ID, when available

Do not send your API secret or other sensitive credentials.