Errors

The Martis API uses conventional HTTP status codes to indicate the success or failure of requests. Codes in the 2xx range indicate success, 4xx codes indicate client errors, and 5xx codes indicate server errors.

HTTP Status Codes

Error Response Format

Error responses follow a consistent structure across all endpoints.

Client Errors (4xx)

{
  "status": "fail",
  "data": {
    "field_name": ["Error message for this field"],
    "another_field": ["First error", "Second error"]
  }
}

Server Errors (5xx)

{
  "status": "error",
  "message": "Internal server error"
}

Error Attributes

Common Error Codes

Authentication Errors

Validation Errors

Payment Errors

Resource Errors

Payout Errors

Idempotency Errors

Error Handling

Best Practices

• Check the status code — Use the HTTP status code to determine the error category
• Parse error messages — Extract field-specific errors from the data object for validation errors
• Implement retries — Retry requests that fail with 5xx errors using exponential backoff
• Log errors — Record error responses for debugging and monitoring
• Handle gracefully — Display user-friendly messages for common errors

Retry Strategy

For transient errors (5xx codes), implement exponential backoff:

async function requestWithRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status < 500 || attempt === maxRetries - 1) {
        throw error;
      }
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

Validation Error Handling

Parse field-specific errors for form validation:

function handleValidationErrors(response) {
  if (response.status === 'fail' && response.data) {
    const errors = {};
    for (const [field, messages] of Object.entries(response.data)) {
      errors[field] = messages[0]; // Use first error message
    }
    return errors;
  }
  return null;
}

Debugging Tips