The Prisme.ai API uses conventional HTTP response codes to indicate the success or failure of an API request. This page provides a comprehensive guide to understanding and handling errors from the API.

​
Error Response Format

All API errors follow a consistent format:

{
  "error": "error_code",
  "message": "A human-readable error message",
  "details": {
    // Additional error-specific information
  }
}

As for any request, you will also receive a x-correlation-id response header that will help you find relevent activity events or application logs.

code

A machine-readable string identifier for the error type. Use this for programmatic error handling.

message

A human-readable description of the error. The message may change over time, so don’t rely on exact message matching.

details

An optional object containing additional information about the error, which varies based on the error type.

requestId

A unique identifier for the request that can be provided to support for troubleshooting.

​
HTTP Status Codes

CodeDescription
200OK - The request succeeded
201Created - A new resource was successfully created
202Accepted - The request has been accepted for processing
204No Content - The request succeeded but returns no content

​
Common Error Codes

​
Error Examples

{
  "error": {
    "code": "invalid_token",
    "message": "The provided token is invalid or has expired",
    "requestId": "req-a1b2c3d4e5f6"
  }
}

​
Handling Errors

1

Check HTTP Status Code

First, check the HTTP status code to understand the general category of the error:

if (response.status >= 400) {
  // Handle error based on status code
  if (response.status === 401) {
    // Authentication issue
  } else if (response.status === 403) {
    // Authorization issue
  } else if (response.status === 429) {
    // Rate limiting issue
  } else {
    // Other error
  }
}
2

Parse Error Code

For more specific error handling, check the error code:

if (response.data && response.data.error) {
  switch (response.data.error.code) {
    case 'token_expired':
      // Refresh the token
      break;
    case 'resource_not_found':
      // Handle missing resource
      break;
    case 'validation_failed':
      // Handle validation errors
      const validationErrors = response.data.error.details.errors;
      // Display validation errors to the user
      break;
    default:
      // Handle other errors
      break;
  }
}
3

Implement Retry Logic

For certain errors, especially 429 (rate limiting) and some 5xx errors, implement retry logic with exponential backoff:

async function apiCallWithRetry(url, options, maxRetries = 3) {
  let retries = 0;
  
  while (retries < maxRetries) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        // Get retry after header if available
        const retryAfter = response.headers.get('Retry-After') || 1;
        const delay = parseInt(retryAfter, 10) * 1000;
        
        await new Promise(resolve => setTimeout(resolve, delay));
        retries++;
        continue;
      }
      
      if (response.status >= 500 && response.status < 600) {
        // Exponential backoff for server errors
        const delay = Math.pow(2, retries) * 1000 + Math.random() * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        retries++;
        continue;
      }
      
      return response;
    } catch (error) {
      if (retries >= maxRetries - 1) {
        throw error;
      }
      
      // Exponential backoff for network errors
      const delay = Math.pow(2, retries) * 1000 + Math.random() * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
      retries++;
    }
  }
}
4

Log Errors

Log errors with their requestId for troubleshooting:

if (response.data && response.data.error) {
  console.error(
    `API Error: ${response.data.error.code} - ${response.data.error.message}`,
    `Request ID: ${response.data.error.requestId}`,
    response.data.error.details
  );
}

The requestId is particularly important when contacting support, as it allows for quick identification of the specific request in server logs.

​
Best Practices

Graceful Degradation

Design your application to function (perhaps with limited capabilities) even when API requests fail.

User-Friendly Messages

Translate error codes into user-friendly messages rather than displaying raw API errors to users.

Centralized Error Handling

Implement a centralized error handling mechanism to ensure consistent handling of errors across your application.

Contextual Recovery

Provide context-specific recovery options based on the error type (e.g., refresh button, edit form, etc.).

Validation Precheck

Validate inputs on the client side before sending requests to reduce validation errors.

Error Tracking

Implement error tracking to monitor error patterns and improve user experience over time.

​
Troubleshooting Common Errors

​
Next Steps

Rate Limits

Learn about API usage limits and quotas

Authentication

Understand how to authenticate with the API

Security

Explore security best practices

Was this page helpful?

Raise issue