Error Codes

This section describes common HTTP error codes that can be returned by Mesilat API.

HTTP Status Codes

Code	Name	Description
200	OK	Request completed successfully
201	Created	Resource created successfully
204	No Content	Request completed successfully, no content returned
400	Bad Request	Invalid request format or parameters
401	Unauthorized	Invalid or missing API key
403	Forbidden	Access denied to resource
404	Not Found	Requested resource not found
422	Unprocessable Entity	Data validation failed
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error occurred

Detailed Error Descriptions

400 Bad Request

Returned when request format is incorrect or required parameters are missing.

{
  "error": "Bad Request",
  "message": "Invalid request format"
}

Common causes: - Missing required parameters - Invalid JSON format - Incorrect data types

401 Unauthorized

Returned when API key is missing, invalid, or revoked.

{
  "error": "API key is required",
  "message": "Please provide a valid API key in the X-API-Key header"
}

{
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked"
}

Solutions: - Check API key in X-API-Key header - Verify key is active and not revoked - Generate new API key if needed

403 Forbidden

Returned when you don't have permission to access the requested resource.

{
  "error": "Forbidden",
  "message": "Access denied to this resource"
}

Solutions: - Check if you have access to the resource - Verify API key permissions - Contact support if access should be granted

404 Not Found

Returned when the requested resource doesn't exist.

{
  "message": "No query results for model [Modules\\Product\\Entities\\ProductPrice] 123"
}

Solutions: - Verify resource ID is correct - Check if resource exists - Ensure resource hasn't been deleted

422 Unprocessable Entity

Returned when request data fails validation.

{
  "message": "The given data was invalid.",
  "errors": {
    "prices": ["The prices field is required."],
    "prices.0.currency_id": ["The currency_id field is required."],
    "metadata": ["The metadata must be an array."]
  }
}

Solutions: - Check validation errors in response - Correct data format according to API documentation - Ensure all required fields are provided

429 Too Many Requests

Returned when rate limit is exceeded.

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later."
}

Rate limits: - 1000 requests per hour per API key - 100 requests per minute per API key

Solutions: - Implement request throttling - Use exponential backoff - Consider upgrading API plan

500 Internal Server Error

Returned when server encounters an unexpected error.

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred. Please try again later."
}

Solutions: - Retry request after delay - Check if issue persists - Contact support if error continues

Error Response Format

All error responses follow this format:

{
  "error": "Error type",
  "message": "Human-readable error description",
  "errors": {
    "field_name": ["Specific validation error"]
  }
}

Handling Errors

Retry Logic

For temporary errors (5xx), implement exponential backoff:

async function makeRequest(url, options, retries = 3) {
  try {
    const response = await fetch(url, options);

    if (response.status >= 500 && retries > 0) {
      await new Promise(resolve => setTimeout(resolve, 1000 * (4 - retries)));
      return makeRequest(url, options, retries - 1);
    }

    return response;
  } catch (error) {
    if (retries > 0) {
      await new Promise(resolve => setTimeout(resolve, 1000 * (4 - retries)));
      return makeRequest(url, options, retries - 1);
    }
    throw error;
  }
}

Error Logging

Always log errors for debugging:

// PHP
try {
    $response = $client->post('/api/endpoint', $data);
} catch (Exception $e) {
    Log::error('API request failed', [
        'url' => '/api/endpoint',
        'error' => $e->getMessage(),
        'response' => $e->getResponse()->getBody()
    ]);
    throw $e;
}

# Python
import logging

try:
    response = requests.post('/api/endpoint', json=data)
    response.raise_for_status()
except requests.exceptions.RequestException as e:
    logging.error(f'API request failed: {e}')
    if hasattr(e, 'response') and e.response is not None:
        logging.error(f'Response: {e.response.text}')
    raise

Best Practices

Always check response status before processing data
Implement proper error handling for all API calls
Log errors for debugging and monitoring
Use retry logic for temporary failures
Respect rate limits to avoid 429 errors
Validate data before sending to API
Handle network timeouts appropriately

Getting Help

If you encounter persistent errors:

Check this documentation for error descriptions
Verify your request format matches API specification
Test with API testing tools (Postman, curl)
Contact support with:
Error response details
Request parameters (without sensitive data)
Timestamp of occurrence