Developers

Appearance

Error Handling ​

This guide explains common HTTP error responses you may encounter when using the VORTEX API and how to handle them properly.

HTTP Status Codes Overview ​

The VORTEX API uses standard HTTP status codes to indicate the success or failure of API requests:

  • 2xx - Success
  • 4xx - Client errors (invalid request, authentication/authorization issues)
  • 5xx - Server errors

Common Error Responses ​

400 Bad Request ​

When it occurs:

  • Invalid request parameters
  • Malformed request body
  • Missing required fields
  • Invalid data format
  • Invalid resource ID

Example Response:

json
{
  "error": "Invalid device ID format"
}

How to fix:

  • Verify all required parameters are included
  • Check parameter data types and formats
  • Ensure request body matches the API specification

401 Unauthorized ​

When it occurs:

  • Missing authentication credentials
  • Invalid or expired API key
  • Missing Authorization header

Example Response:

json
{
  "error": "Unauthorized"
}

How to fix:

  • Ensure you include the Authorization header in your request
  • Verify your API key is valid and not expired
  • Use the correct format: Authorization: Bearer YOUR_API_KEY
  • Refer to the API Authentication guide for more details

403 Forbidden ​

When it occurs:

  • Valid authentication but insufficient permissions
  • Your role or customized permissions don't allow the requested operation

Example Response:

json
{
  "error": "Not authorized"
}

How to fix:

  • Check your user role and permissions with your organization administrator
  • Verify the API key was created by a user with appropriate permissions
  • Refer to the API Authorization guide for more details

404 Not Found ​

When it occurs:

  • Requested resource doesn't exist
  • Resource has been deleted
  • Incorrect API endpoint URL

How to fix:

  • Verify the resource ID is correct
  • Check if the resource still exists
  • Ensure you're using the correct API endpoint

500 Internal Server Error ​

When it occurs:

  • Unexpected server-side error
  • Service malfunction

Example Response:

json
{
  "error": "Error retrieving device"
}

How to fix:

  • Retry the request after a short delay
  • If the error persists, contact VORTEX support

502 Bad Gateway ​

When it occurs:

  • Gateway or proxy server received an invalid response
  • Upstream service is unavailable

How to fix:

  • Retry the request after a short delay
  • If the error persists, contact VORTEX support

503 Service Unavailable ​

When it occurs:

  • Scheduled maintenance in progress
  • Service temporarily overloaded

Example Response:

json
{
  "type": "/problems/service-unavailable/maintenance",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Scheduled maintenance in progress. Please retry later."
}

How to fix:

  • Wait and retry after the maintenance window
  • Check the Retry-After header if provided
  • Implement exponential backoff in your retry logic

Error Response Format ​

Most error responses use a simple format:

json
{
  "error": "Error message description"
}

The 503 Service Unavailable error follows the RFC 7807 Problem Details standard:

json
{
  "type": "/problems/service-unavailable/maintenance",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Scheduled maintenance in progress. Please retry later."
}