Error Handling

Overview

The Connect2Print API uses standard HTTP status codes and structured error responses to communicate problems. This guide helps you understand and handle errors correctly.

Error Response Format

All API errors are returned in the following standard format:

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Invalid input data",
    "details": {
      "email": ["Email format is invalid"],
      "quantity": ["Must be at least 1"]
    }
  }
}

Response Fields:

• success - Always false for errors
• error - Object containing error details
• error.code - Machine-readable error code
• error.message - Human-readable error message
• error.details - (Optional) Additional error information

HTTP Status Codes

The API uses standard HTTP status codes:

Error Codes Reference

The API uses the following error codes:

Error Examples

Validation Error (400)

HTTP/1.1 400 Bad Request

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": {
      "email": ["Email format is invalid"],
      "quantity": ["Must be between 1 and 1000"]
    }
  }
}

Unauthorized (401)

HTTP/1.1 401 Unauthorized

{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

Forbidden (403)

HTTP/1.1 403 Forbidden

{
  "success": false,
  "error": {
    "code": "insufficient_permissions",
    "message": "API key lacks required scope: orders:write"
  }
}

Not Found (404)

HTTP/1.1 404 Not Found

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Order not found"
  }
}

Rate Limit (429)

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds."
  }
}

Error Handling Best Practices

Follow these best practices when handling API errors:

Code Examples

Examples of error handling in different languages:

PHP Error Handling

try {
    $response = makeApiRequest($url, $apiKey);

    if (!$response['success']) {
        $errorCode = $response['error']['code'];
        $errorMessage = $response['error']['message'];

        switch ($errorCode) {
            case 'unauthorized':
                handleUnauthorized();
                break;
            case 'validation_error':
                handleValidationError($response['error']['details']);
                break;
            case 'rate_limit_exceeded':
                handleRateLimit();
                break;
            default:
                handleGenericError($errorMessage);
        }
    }
} catch (Exception $e) {
    error_log("API request failed: " . $e->getMessage());
}

Node.js Error Handling

try {
  const response = await makeApiRequest(url, apiKey);

  if (!response.success) {
    const { code, message, details } = response.error;

    switch (code) {
      case 'unauthorized':
        handleUnauthorized();
        break;
      case 'validation_error':
        handleValidationError(details);
        break;
      case 'rate_limit_exceeded':
        await handleRateLimit();
        break;
      default:
        handleGenericError(message);
    }
  }
} catch (error) {
  console.error('API request failed:', error);
}

Python Error Handling

try:
    response = make_api_request(url, api_key)

    if not response['success']:
        error = response['error']
        code = error['code']
        message = error['message']

        if code == 'unauthorized':
            handle_unauthorized()
        elif code == 'validation_error':
            handle_validation_error(error.get('details'))
        elif code == 'rate_limit_exceeded':
            handle_rate_limit()
        else:
            handle_generic_error(message)

except Exception as e:
    print(f'API request failed: {e}')

Debugging Tips

Tips for debugging API issues:

Next Steps

Explore related topics: