Error Handling

This guide explains how the mnml.ai API communicates errors and provides best practices for handling them in your applications.

Error Response Format

When an error occurs, the API returns an HTTP status code and a JSON response body with error details. All API errors follow this consistent format:

Error Response Format

{
  "status": "error",
  "message": "Descriptive error message",
  "code": "error_code",   // Optional: specific error code
  "details": { }         // Optional: additional error details
}

Common Errors

The API uses standard HTTP status codes to indicate the general category of an error:

Status Code	Error Type	Description
`400`	Bad Request	The request is invalid or missing required parameters
`401`	Unauthorized	Authentication failed or API key is missing
`403`	Forbidden	You don't have permission to access this resource
`404`	Not Found	The requested resource or endpoint doesn't exist
`429`	Too Many Requests	You've exceeded the rate limit for API requests
`500`	Internal Server Error	Something went wrong on our servers
`503`	Service Unavailable	The service is temporarily unavailable

Authentication Errors

Authentication errors occur when there are issues with your API key or credentials.

Example: Missing API Key

// 401 Unauthorized
{
  "status": "error",
  "message": "Missing API key. Please include your API key in the Authorization header.",
  "code": "missing_api_key"
}

Example: Invalid API Key

// 401 Unauthorized
{
  "status": "error",
  "message": "Invalid API key provided.",
  "code": "invalid_api_key"
}

Validation Errors

Validation errors occur when the request parameters don't meet the requirements.

Example: Missing Required Field

// 400 Bad Request
{
  "status": "error",
  "message": "The 'prompt' field is required.",
  "code": "missing_required_field",
  "details": {
    "field": "prompt"
  }
}

Example: Invalid Image Format

// 400 Bad Request
{
  "status": "error",
  "message": "Unsupported image format. Please upload JPEG, PNG, or WebP.",
  "code": "invalid_image_format"
}

Rate Limit Errors

Rate limit errors occur when you exceed the allowed number of requests in a given time period.

Example: Rate Limit Exceeded

// 429 Too Many Requests
{
  "status": "error",
  "message": "Rate limit exceeded. Please try again later.",
  "code": "rate_limit_exceeded",
  "details": {
    "retry_after": 30
  }
}

When you receive a rate limit error, check the retry_after value in the response. This indicates the number of seconds to wait before making another request.

Server Errors

Server errors indicate problems on our end. These are usually temporary and should be retried after a short delay.

Example: Internal Server Error

// 500 Internal Server Error
{
  "status": "error",
  "message": "An unexpected error occurred. Please try again later.",
  "code": "internal_server_error"
}

Example: Service Unavailable

// 503 Service Unavailable
{
  "status": "error",
  "message": "Service temporarily unavailable. Please try again later.",
  "code": "service_unavailable",
  "details": {
    "retry_after": 300
  }
}

Resource Errors

Resource errors occur when requested resources don't exist or are unavailable.

Example: Resource Not Found

// 404 Not Found
{
  "status": "error",
  "message": "Request ID not found.",
  "code": "resource_not_found"
}

Example: Invalid Request ID

// 400 Bad Request
{
  "status": "error",
  "message": "Invalid request ID format.",
  "code": "invalid_request_id"
}

Example: Insufficient Credits

// 403 Forbidden
{
  "status": "error",
  "message": "Insufficient credits to perform this operation.",
  "code": "insufficient_credits",
  "details": {
    "available_credits": 0,
    "required_credits": 1
  }
}

Error Handling Best Practices

Implement retry logic with exponential backoff

For 429 (rate limit) and 5xx (server) errors, retry the request after increasing delays.

// Example retry logic in JavaScript
const MAX_RETRIES = 3;
let retryCount = 0;
let backoffTime = 1000; // Start with 1 second

async function makeRequestWithRetry() {
  try {
    const response = await makeApiRequest();
    return response;
  } catch (error) {
    if (shouldRetry(error) && retryCount < MAX_RETRIES) {
      retryCount++;
      // Exponential backoff: 1s, 2s, 4s
      await sleep(backoffTime);
      backoffTime *= 2;
      return makeRequestWithRetry();
    }
    throw error;
  }
}

function shouldRetry(error) {
  // Retry on rate limits and server errors
  return error.status === 429 || error.status >= 500;
}

Validate inputs before sending
Implement client-side validation to catch common errors before sending requests.
Provide clear error messages to users
Translate API error messages into user-friendly notifications in your application.
Log errors for debugging
Maintain detailed logs of API errors to help troubleshoot issues.

Troubleshooting

Common Issues and Solutions

401 Unauthorized errors

Check that your API key is valid and hasn't expired
Ensure your API key is correctly formatted in the Authorization header
Verify you're using the correct API key for the environment (test vs. production)

400 Bad Request errors

Verify all required parameters are included in your request
Check that parameter values are within the allowed ranges
Ensure image files meet size and format requirements
Review the specific error message for details on what needs to be fixed

429 Rate Limit errors

Implement proper request throttling in your application
Use the retry-after header to determine when to retry
Consider upgrading your plan if you consistently hit rate limits

5xx Server errors

Wait a few minutes and retry the request
Check the API status page for any ongoing issues
If problems persist, contact support with your request details

If you're experiencing persistent issues that aren't addressed in this documentation, please contact our support team with your API key, request details, and the full error response.