Skip to main content
The Maash API uses standard HTTP status codes and returns structured JSON error responses. This page covers the error format, common error codes, and how to handle them.

​
Error response format

All error responses follow this structure: 
{
  "error": "Human-readable error message",
  "details": {
    "validation_errors": ["field: description of the issue"]
  }
}
FieldTypeDescription
errorstringA human-readable description of the error
detailsobjectAdditional context, including an array of validation errors

​
HTTP status codes

StatusMeaningWhen it occurs
400Bad RequestInvalid request body, missing required fields, or validation failure
401UnauthorizedMissing or invalid authentication credentials
403ForbiddenValid credentials but insufficient permissions
404Not FoundRequested resource does not exist
410GoneCheckout session has expired
500Internal Server ErrorUnexpected server-side failure

​
Error codes

CodeDescription
invalid_transaction_dataRequest body failed schema validation
no_fields_to_updateUpdate request contained no valid fields
| Code | Description | |------|-------------| | authentication_required | No API key or session token provided | | invalid_api_key | The provided API key is not valid | | session_expired | The session token has expired |
| Code | Description | |------|-------------| | failed_to_create_transaction | Could not create the resource in the database | | failed_to_update_transaction | Could not update the resource in the database | | database_operation_failed | General database operation failure |
| Code | Description | |------|-------------| | missing_required_env_vars | Server misconfiguration (contact support) |
CodeDescription
notification_errorFailed to send a notification or webhook

​
Handling errors in your integration

Check the details.validation_errors array for field-level messages:
{
  "error": "Validation failed",
  "details": {
    "validation_errors": [
      "amount_usd: Number must be greater than 0",
      "webhook_url: Must be a valid HTTPS URL"
    ]
  }
}
Fix the indicated fields and retry the request.
Verify that your API key is correct and has not been revoked:
# Check that both required headers are correct
curl https://api.maash.io/checkout/sessions \
  -H "x-api-key: mk_live_1234567890abcdef1234567890abcdef" \
  -H "x-maash-user-type: checkout"
Create a new checkout session. Expired sessions cannot be reactivated:
{
  "error": "Checkout session has expired"
}
These indicate an issue on the Maash side. Retry the request with exponential backoff. If the error persists, contact support.
For transient errors (5xx responses and network timeouts), use exponential backoff: 
async function callWithRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      if (error.status >= 400 && error.status < 500) throw error; // Don't retry client errors

      const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
}
Do not retry 4xx errors. These indicate a problem with your request that must be fixed before retrying.

​
Next steps

Webhooks

Handle webhook delivery failures and retry policies.

Authentication

Troubleshoot authentication errors with API keys and session tokens.

Testing

Test error handling in sandbox mode before going live.

API Reference

See detailed request and response formats for each endpoint.