Error Handling

Learn how the Management API handles errors, common error codes, error response formats, and best practices for error handling.

​

Overview

The Management API uses standard HTTP status codes and returns error responses in a consistent JSON format.

​

HTTP Status Codes

Status Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters or body
401	Unauthorized	Authentication failed or token invalid
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
409	Conflict	Resource conflict (e.g., duplicate name)
500	Internal Server Error	Server error

​

Error Response Format

All error responses follow this format:

{
  "error": "error_code",
  "error_description": "Human-readable error message"
}

​

Common Error Codes

​

400 Bad Request

​

Error Codes

• bad_request - General validation error
• validation_failed - Request validation failed
• invalid_parameter - Invalid parameter value

​

Example Response

{
  "error": "validation_failed",
  "error_description": "Validation failed: name is required"
}

​

Common Causes

• Missing required fields
• Invalid field values
• Invalid data types
• Validation rule violations

​

401 Unauthorized

​

Error Codes

• unauthorized_client - Invalid credentials
• invalid_token - Token is invalid or expired
• token_expired - Token has expired

​

Example Response

{
  "error": "invalid_token",
  "error_description": "Token is invalid or expired"
}

​

Common Causes

• Missing Authorization header
• Invalid token format
• Expired token
• Revoked token

​

403 Forbidden

​

Error Codes

• forbidden - Insufficient permissions
• access_denied - Access denied for this resource

​

Example Response

{
  "error": "forbidden",
  "error_description": "You do not have permission to perform this action"
}

​

Common Causes

• User lacks required role
• Resource access restrictions
• Project-level permissions

​

404 Not Found

​

Error Codes

• not_found - Resource not found
• resource_not_found - Specific resource not found

​

Example Response

{
  "error": "not_found",
  "error_description": "Project 'MyProject' not found"
}

​

Common Causes

• Incorrect resource name
• Resource was deleted
• Wrong project/environment context

​

409 Conflict

​

Error Codes

• conflict - Resource conflict
• duplicate_name - Name already exists

​

Example Response

{
  "error": "duplicate_name",
  "error_description": "API Proxy with name 'MyAPI' already exists"
}

​

Common Causes

• Duplicate resource name
• Unique constraint violation

​

500 Internal Server Error

​

Error Codes

• internal_error - Internal server error
• server_error - Unexpected server error

​

Example Response

{
  "error": "internal_error",
  "error_description": "An unexpected error occurred. Please try again later."
}

​

Common Causes

• Database errors
• System failures
• Unexpected exceptions

​

Error Handling Best Practices

​

1. Check Status Codes

Always check the HTTP status code before processing the response:

# Good
if response.status_code == 200:
    process_success(response.json())
else:
    handle_error(response.json())

# Bad
process_success(response.json())  # May fail on error responses

​

2. Parse Error Messages

Extract and log error messages for debugging:

{
  "error": "validation_failed",
  "error_description": "Field 'name' is required"
}

​

3. Handle Specific Errors

Handle specific error codes differently:

if error_code == "invalid_token":
    refresh_token()
elif error_code == "not_found":
    log_not_found(resource_name)
elif error_code == "validation_failed":
    show_validation_errors(error_description)

​

4. Retry Logic

Implement retry logic for transient errors (500, network errors):

max_retries = 3
for attempt in range(max_retries):
    try:
        response = make_request()
        if response.status_code == 200:
            return response
    except Exception as e:
        if attempt == max_retries - 1:
            raise
        time.sleep(2 ** attempt)  # Exponential backoff

​

5. Logging

Log errors for debugging and monitoring:

logger.error(f"API Error: {error_code} - {error_description}")
logger.debug(f"Request: {request_url}")
logger.debug(f"Response: {response_body}")

​

Validation Errors

Validation errors may include field-specific information:

{
  "error": "validation_failed",
  "error_description": "Validation failed",
  "validation_errors": [
    {
      "field": "name",
      "message": "Name is required"
    },
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

​

Rate Limiting Errors

When rate limits are exceeded, you may receive:

{
  "error": "rate_limit_exceeded",
  "error_description": "Rate limit exceeded. Please try again later.",
  "retry_after": 60
}

The retry_after field indicates seconds to wait before retrying.

​

Troubleshooting

​

Common Issues

1. 401 Unauthorized

   • Check token validity
   • Verify Authorization header format
   • Ensure token hasn’t expired
2. 404 Not Found

   • Verify resource names (case-sensitive)
   • Check project/environment context
   • Ensure resource exists
3. 400 Bad Request

   • Validate request body against schema
   • Check required fields
   • Verify data types
4. 500 Internal Server Error

   • Retry the request
   • Check system status
   • Contact support if persistent

​

Next Steps

• Explore the API reference - Complete API endpoint documentation