Error Handling Guide

Guide in Progress

This guide is currently under development and may change as we improve our error handling standards.

Please note that error codes and messages are not yet fully consistent and may be updated without notice. Your feedback is welcome, but any changes you make could be overwritten in future updates.

Overview

The DeePsy API uses standard HTTP status codes combined with detailed error information to help you understand and handle errors effectively. All errors follow a consistent format and include specific error codes for programmatic handling.

Error Response Format

All API errors return a consistent JSON structure:

{
  "error": "Human-readable error description",
  "error_code": "MACHINE_READABLE_ERROR_CODE"
}

Example Error Response

{
  "error": "You do not have the required permissions to access this resource",
  "error_code": "INSUFFICIENT_PERMISSIONS"
}

Common Error Codes

Authentication Errors (401)

Error Code	Description	Solution
API_KEY_NOT_PROVIDED	No API key in Authorization header	Include Authorization: Bearer deepsy-dev-your-key
INVALID_API_KEY_FORMAT	API key format is incorrect	Ensure key starts with deepsy-dev-
INVALID_API_KEY	API key doesn't exist or is invalid	Check your API key in dashboard settings
API_KEY_INACTIVE	API key has been deactivated	Regenerate your API key

Permission Errors (403)

Error Code	Description	Solution
USER_NOT_IN_COMPANY	User is not a member of the company	Join the company or use correct company ID
NO_PERMISSIONS_FOUND	No permissions for this company	Contact company admin for permission grant
INSUFFICIENT_PERMISSIONS	Missing required permissions	Request additional permissions from admin

Missing Subscription/Credits Errors (402)

Error Code	Description	Solution
ACTIVE_SUBSCRIPTION_REQUIRED	Company subscription is inactive	Renew company subscription

Validation Errors (422)

Error Code	Description	Solution
NO_COMPANY_MEMBERSHIP	User must belong to at least one company	Join a company before using the API

Specific Error Scenarios

Authentication Setup

JavaScript

async function setupAuthentication(apiKey) {
  try {
    const response = await fetch('https://deepsy.fr/api/v1/health', {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    });

    if (!response.ok) {
      const error = await response.json();

      switch (error.error_code) {
        case 'API_KEY_NOT_PROVIDED':
          throw new Error('Please provide your API key');
        case 'INVALID_API_KEY_FORMAT':
          throw new Error('API key format is invalid. Check your key format.');
        case 'INVALID_API_KEY':
          throw new Error('API key is invalid. Please check your dashboard.');
        case 'API_KEY_INACTIVE':
          throw new Error('API key is inactive. Please regenerate it.');
        default:
          throw new Error(`Authentication failed: ${error.error}`);
      }
    }

    return true;
  } catch (error) {
    console.error('Authentication setup failed:', error.message);
    throw error;
  }
}

TypeScript

interface ApiError {
  error: string;
  error_code: string;
}

async function setupAuthentication(apiKey: string): Promise<boolean> {
  try {
    const response = await fetch('https://deepsy.fr/api/v1/health', {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    });

    if (!response.ok) {
      const error: ApiError = await response.json();

      switch (error.error_code) {
        case 'API_KEY_NOT_PROVIDED':
          throw new Error('Please provide your API key');
        case 'INVALID_API_KEY_FORMAT':
          throw new Error('API key format is invalid. Check your key format.');
        case 'INVALID_API_KEY':
          throw new Error('API key is invalid. Please check your dashboard.');
        case 'API_KEY_INACTIVE':
          throw new Error('API key is inactive. Please regenerate it.');
        default:
          throw new Error(`Authentication failed: ${error.error}`);
      }
    }

    return true;
  } catch (error) {
    console.error('Authentication setup failed:', (error as Error).message);
    throw error;
  }
}

PHP

<?php
function setupAuthentication($apiKey) {
    try {
        $curl = curl_init();

        curl_setopt_array($curl, [
            CURLOPT_URL => 'https://deepsy.fr/api/v1/health',
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => [
                "Authorization: Bearer $apiKey"
            ],
        ]);

        $response = curl_exec($curl);
        $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
        curl_close($curl);

        if ($httpCode !== 200) {
            $error = json_decode($response, true);

            switch ($error['error_code']) {
                case 'API_KEY_NOT_PROVIDED':
                    throw new Exception('Please provide your API key');
                case 'INVALID_API_KEY_FORMAT':
                    throw new Exception('API key format is invalid. Check your key format.');
                case 'INVALID_API_KEY':
                    throw new Exception('API key is invalid. Please check your dashboard.');
                case 'API_KEY_INACTIVE':
                    throw new Exception('API key is inactive. Please regenerate it.');
                default:
                    throw new Exception("Authentication failed: " . $error['error']);
            }
        }

        return true;
    } catch (Exception $e) {
        error_log('Authentication setup failed: ' . $e->getMessage());
        throw $e;
    }
}
?>

Related Guides

• Authentication Guide - Resolve authentication errors
• Permissions Guide - Understand permission-related errors
• Quick Start Guide - Basic API usage and error handling
• Company Users Guide - Handle user-related errors