Errors

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

2xx Success
4xx Client Errors
5xx Server Errors

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

Code	Description
400	Bad Request - The request contains invalid parameters or syntax
401	Unauthorized - Authentication is required or has failed
403	Forbidden - The authenticated user doesn’t have sufficient permissions
404	Not Found - The requested resource does not exist
409	Conflict - The request conflicts with the current state of the resource
422	Unprocessable Entity - The request was well-formed but contains semantic errors
429	Too Many Requests - You’ve exceeded the rate limits

Code	Description
500	Internal Server Error - Something went wrong on our servers
502	Bad Gateway - A service required to fulfill the request is unavailable
503	Service Unavailable - The server is temporarily unavailable
504	Gateway Timeout - A service required to fulfill the request timed out

Common Error Codes

Authentication Errors

Code	HTTP Status	Description
`invalid_token`	401	The provided token is invalid, expired, or has been revoked
`missing_token`	401	No authentication token was provided
`invalid_credentials`	401	The provided username/password or API key is incorrect
`token_expired`	401	The provided token has expired

Authorization Errors

Code	HTTP Status	Description
`permission_denied`	403	The authenticated user lacks the necessary permissions
`insufficient_scope`	403	The token doesn’t have the required scopes for this action
`workspace_access_denied`	403	The user doesn’t have access to the specified workspace
`organization_access_denied`	403	The user doesn’t have access to the specified organization

Resource Errors

Code	HTTP Status	Description
`resource_not_found`	404	The requested resource does not exist
`resource_already_exists`	409	A resource with the specified identifier already exists
`resource_conflict`	409	The request conflicts with the current state of the resource
`resource_locked`	423	The resource is currently locked and cannot be modified

Validation Errors

Code	HTTP Status	Description
`invalid_request`	400	The request body or parameters are invalid
`invalid_parameter`	400	A specific parameter has an invalid value
`missing_parameter`	400	A required parameter is missing
`validation_failed`	422	The input failed validation checks

Rate Limiting Errors

Code	HTTP Status	Description
`rate_limit_exceeded`	429	You’ve exceeded the rate limit for this endpoint
`quota_exceeded`	429	You’ve exceeded your usage quota
`concurrent_request_limit`	429	Too many concurrent requests

Server Errors

Code	HTTP Status	Description
`internal_error`	500	An unexpected error occurred on the server
`service_unavailable`	503	The service is temporarily unavailable
`gateway_timeout`	504	A dependent service timed out
`database_error`	500	A database operation failed

Error Examples

Invalid Token
Resource Not Found
Validation Error
Rate Limit Exceeded

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

{
  "error": {
    "code": "resource_not_found",
    "message": "The requested workspace could not be found",
    "details": {
      "resourceType": "workspace",
      "resourceId": "ws-12345"
    },
    "requestId": "req-g7h8i9j0k1l2"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "The request contains invalid parameters",
    "details": {
      "errors": [
        {
          "field": "name",
          "message": "must be between 3 and 50 characters"
        },
        {
          "field": "description",
          "message": "cannot exceed 500 characters"
        }
      ]
    },
    "requestId": "req-m3n4o5p6q7r8"
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "details": {
      "limit": 100,
      "period": "1m",
      "resetAt": "2025-04-06T12:30:00Z"
    },
    "requestId": "req-s9t0u1v2w3x4"
  }
}

Handling Errors

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
  }
}

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;
  }
}

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++;
    }
  }
}

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

Authentication Failed

If you receive a 401 error:

Check that your token is correctly formatted in the Authorization header
Verify that your token hasn’t expired
Ensure you’re using the correct authentication method for the endpoint
Try generating a new token

# Example of correct token usage
curl -X GET "https://api.studio.prisme.ai/v2/workspaces" \
     -H "Authorization: Bearer YOUR_TOKEN"

Permission Denied

If you receive a 403 error:

Verify that the authenticated user has the necessary permissions
Check if you’re using an API key with limited scopes
Ensure you’re accessing resources within the correct workspace
Check if the resource has additional access controls

Common permission errors include attempting to access:

Resources in workspaces you’re not a member of
Admin-only functionality without admin privileges
Resources owned by other users

Rate Limit Exceeded

If you receive a 429 error:

Implement proper rate limit handling with backoff
Check the Retry-After header for guidance on when to retry
Optimize your code to batch requests where possible
Consider upgrading your plan if you consistently hit limits

See the Rate Limits page for more details on rate limiting.

Invalid Parameters

If you receive a 400 or 422 error:

Check the details field in the error response for specific validation failures
Verify that you’re sending the correct data types
Check for required fields that might be missing
Ensure values are within acceptable ranges or formats

// Example validation error details
"details": {
  "errors": [
    {
      "field": "email",
      "message": "must be a valid email address"
    }
  ]
}

Next Steps

Rate Limits

Learn about API usage limits and quotas

Authentication

Understand how to authenticate with the API

Security

Explore security best practices

Introduction

Platform API

Agent Creator API

LLM Gateway API

Governance API

Error Response Format

code

message

details

requestId

HTTP Status Codes

Common Error Codes

Error Examples

Handling Errors

Best Practices

Graceful Degradation

User-Friendly Messages

Centralized Error Handling

Contextual Recovery

Validation Precheck

Error Tracking

Troubleshooting Common Errors

Next Steps

Rate Limits

Authentication

Security

​Error Response Format

code

message

details

requestId

​HTTP Status Codes

​Common Error Codes

​Error Examples

​Handling Errors

​Best Practices

Graceful Degradation

User-Friendly Messages

Centralized Error Handling

Contextual Recovery

Validation Precheck

Error Tracking

​Troubleshooting Common Errors

​Next Steps

Rate Limits

Authentication

Security

Error Response Format

HTTP Status Codes

Common Error Codes

Error Examples

Handling Errors

Best Practices

Troubleshooting Common Errors

Next Steps