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