Error Handling

The PaiTIENT Secure Model Service uses standard HTTP status codes and structured error responses to communicate API errors. This document details the error format and common error codes.

Error Response Format

All API errors are returned in a consistent JSON format:

{
  "error": {
    "code": "invalid_request",
    "message": "The request was invalid or malformed.",
    "param": "deployment_name",
    "details": "Deployment name must be between 3 and 64 characters.",
    "request_id": "req_abcdefghijk"
  }
}

The error object includes:

• code: A machine-readable error code
• message: A human-readable error message
• param: The parameter that caused the error (if applicable)
• details: Additional details about the error
• request_id: A unique identifier for the request, useful for troubleshooting

HTTP Status Codes

Status Code	Description
400	Bad Request - The request was invalid or cannot be served
401	Unauthorized - Authentication is required or failed
403	Forbidden - The request is not allowed
404	Not Found - The requested resource does not exist
409	Conflict - The request conflicts with current state
422	Unprocessable Entity - The request is well-formed but cannot be processed
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Something went wrong on our end
503	Service Unavailable - The service is temporarily unavailable

Common Error Codes

Authentication Errors

Error Code	Description
invalid_api_key	The API key is invalid
missing_api_key	No API key was provided
expired_api_key	The API key has expired
missing_client_id	No client ID was provided
invalid_client_id	The client ID is invalid

Request Errors

Error Code	Description
invalid_request	The request is malformed or invalid
invalid_parameters	One or more parameters are invalid
missing_required_parameter	A required parameter is missing
parameter_type_error	A parameter is of the wrong type
invalid_json	The request body is not valid JSON

Resource Errors

Error Code	Description
resource_not_found	The requested resource does not exist
resource_exists	The resource already exists
resource_unavailable	The resource is temporarily unavailable
resource_locked	The resource is locked and cannot be modified
deployment_failed	The deployment failed to create

Rate Limit Errors

Error Code	Description
rate_limit_exceeded	You have exceeded the rate limit
quota_exceeded	You have exceeded your usage quota
concurrent_requests_limit	Too many concurrent requests

Server Errors

Error Code	Description
internal_error	An internal error occurred
service_unavailable	The service is temporarily unavailable
model_unavailable	The requested model is temporarily unavailable
maintenance_in_progress	The service is undergoing maintenance

Handling Errors in SDK

Python SDK

The Python SDK raises exceptions for API errors:

from paitient_secure_model import Client
from paitient_secure_model.exceptions import (
    PaiTIENTApiError,
    AuthenticationError,
    ResourceNotFoundError,
    RateLimitError
)

client = Client()

try:
    deployment = client.get_deployment("non-existent-id")
except ResourceNotFoundError as e:
    print(f"Resource not found: {e.message}")
    print(f"Request ID for troubleshooting: {e.request_id}")
except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")
except RateLimitError as e:
    print(f"Rate limit exceeded, retry after {e.retry_after} seconds")
except PaiTIENTApiError as e:
    print(f"API error: {e.code} - {e.message}")

JavaScript SDK

The JavaScript SDK uses a promise-based error handling approach:

const { PaiTIENTClient } = require('paitient-secure-model');
const { 
  PaiTIENTApiError, 
  AuthenticationError, 
  ResourceNotFoundError, 
  RateLimitError 
} = require('paitient-secure-model/errors');

const client = new PaiTIENTClient();

client.getDeployment('non-existent-id')
  .then(deployment => {
    console.log('Deployment:', deployment);
  })
  .catch(error => {
    if (error instanceof ResourceNotFoundError) {
      console.log(`Resource not found: ${error.message}`);
      console.log(`Request ID for troubleshooting: ${error.requestId}`);
    } else if (error instanceof AuthenticationError) {
      console.log(`Authentication failed: ${error.message}`);
    } else if (error instanceof RateLimitError) {
      console.log(`Rate limit exceeded, retry after ${error.retryAfter} seconds`);
    } else if (error instanceof PaiTIENTApiError) {
      console.log(`API error: ${error.code} - ${error.message}`);
    } else {
      console.log(`Unexpected error: ${error.message}`);
    }
  });

Retrying Failed Requests

For transient errors (such as 429 or 503), implement a retry mechanism with exponential backoff:

Python Example

import time
from paitient_secure_model import Client
from paitient_secure_model.exceptions import RateLimitError, ServiceUnavailableError

client = Client()

def with_retry(operation, max_retries=5, initial_backoff=1):
    retries = 0
    while True:
        try:
            return operation()
        except (RateLimitError, ServiceUnavailableError) as e:
            if retries >= max_retries:
                raise
            
            # Calculate backoff time (with jitter)
            backoff = initial_backoff * (2 ** retries) + (random.random() * 0.5)
            
            # Use retry-after header if available
            if hasattr(e, 'retry_after') and e.retry_after:
                backoff = e.retry_after
            
            print(f"Request failed, retrying in {backoff} seconds...")
            time.sleep(backoff)
            retries += 1

# Usage
deployment = with_retry(lambda: client.get_deployment("deployment-id"))

JavaScript Example

const { PaiTIENTClient } = require('paitient-secure-model');
const { RateLimitError, ServiceUnavailableError } = require('paitient-secure-model/errors');

const client = new PaiTIENTClient();

async function withRetry(operation, maxRetries = 5, initialBackoff = 1) {
  let retries = 0;
  while (true) {
    try {
      return await operation();
    } catch (error) {
      if (!(error instanceof RateLimitError || error instanceof ServiceUnavailableError) || 
          retries >= maxRetries) {
        throw error;
      }
      
      // Calculate backoff time (with jitter)
      let backoff = initialBackoff * (2 ** retries) + (Math.random() * 0.5);
      
      // Use retry-after header if available
      if (error.retryAfter) {
        backoff = error.retryAfter;
      }
      
      console.log(`Request failed, retrying in ${backoff} seconds...`);
      await new Promise(resolve => setTimeout(resolve, backoff * 1000));
      retries++;
    }
  }
}

// Usage
async function getDeployment() {
  const deployment = await withRetry(() => client.getDeployment('deployment-id'));
  console.log('Deployment:', deployment);
}

Validation Errors

For 422 Unprocessable Entity errors, the error response includes detailed validation errors:

{
  "error": {
    "code": "validation_error",
    "message": "The request contains invalid parameters",
    "request_id": "req_abcdefghijk",
    "validation_errors": [
      {
        "field": "min_replicas",
        "code": "less_than_minimum",
        "message": "Value must be at least 1"
      },
      {
        "field": "max_replicas",
        "code": "greater_than_maximum",
        "message": "Value must be at most 10"
      }
    ]
  }
}

Next Steps

• Learn about Authentication
• Explore the REST API
• Review the Python SDK or JavaScript SDK