Error Handling

The FaceSign API uses conventional HTTP response codes to indicate the success or failure of an API request. Understanding these errors and implementing proper error handling is crucial for building a robust integration.

HTTP status codes

FaceSign returns the following HTTP status codes:

Name
200 OK
Description
The request was successful.
Name
201 Created
Description
The resource was successfully created.
Name
400 Bad Request
Description
The request was invalid or cannot be served. Check the error message for details.
Name
401 Unauthorized
Description
The request requires authentication or the API key is invalid.
Name
403 Forbidden
Description
The API key doesn't have permissions to perform the request.
Name
404 Not Found
Description
The requested resource doesn't exist.
Name
409 Conflict
Description
The request conflicts with another request (perhaps using the same idempotency key).
Name
429 Too Many Requests
Description
Too many requests hit the API too quickly. We recommend implementing exponential backoff.
Name
500 Internal Server Error
Description
Something went wrong on FaceSign's end. These are rare.

Error response format

All error responses follow a consistent format:

Error response

{
  "error": {
    "type": "invalid_request_error",
    "message": "The 'mode' parameter is required.",
    "param": "mode",
    "code": "parameter_missing"
  }
}

Error object properties

Name
type
Type
string
Description
The type of error returned. See error types below.
Name
message
Type
string
Description
A human-readable message providing more details about the error.
Name
param
Type
string
Description
The parameter the error relates to if the error is parameter-specific.
Name
code
Type
string
Description
A short string uniquely identifying the problem.

Error types

Name
api_error
Description
API errors cover any other type of problem (e.g., a temporary problem with FaceSign's servers).
Name
authentication_error
Description
Failure to properly authenticate in the request.
Name
invalid_request_error
Description
Invalid request errors arise when your request has invalid parameters.
Name
rate_limit_error
Description
Too many requests hit the API too quickly.
Name
validation_error
Description
Errors triggered by our validation system (e.g., invalid email format).

Handling errors

Here's how to properly handle errors in your integration:

Error handling examples

import { FaceSign } from '@facesign/sdk';

const facesign = new FaceSign({
  apiKey: process.env.FACESIGN_API_KEY,
});

try {
  const session = await facesign.sessions.create({
    mode: 'redirect',
    success_url: 'https://example.com/success',
    cancel_url: 'https://example.com/cancel',
  });
} catch (error) {
  if (error.type === 'invalid_request_error') {
    // Handle invalid parameters
    console.error(`Invalid parameter: ${error.param}`);
    console.error(`Error message: ${error.message}`);
  } else if (error.type === 'authentication_error') {
    // Handle authentication errors
    console.error('Check your API key');
  } else if (error.statusCode === 429) {
    // Handle rate limiting
    console.error('Rate limited. Retry after:', error.headers['retry-after']);
  } else {
    // Handle other errors
    console.error('An unexpected error occurred:', error.message);
  }
}

Common errors and solutions

Authentication errors

Invalid API key

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key provided.",
    "code": "invalid_api_key"
  }
}

Solution: Check that you're using the correct API key and that it hasn't been revoked.

Invalid request errors

Missing required parameter

{
  "error": {
    "type": "invalid_request_error",
    "message": "The 'success_url' parameter is required.",
    "param": "success_url",
    "code": "parameter_missing"
  }
}

Solution: Ensure all required parameters are included in your request.

Rate limit errors

Rate limit exceeded

{
  "error": {
    "type": "rate_limit_error",
    "message": "Too many requests. Please retry after 60 seconds.",
    "code": "rate_limit_exceeded"
  }
}

Solution: Implement exponential backoff and respect the Retry-After header.

Implementing retry logic

For transient errors and rate limiting, implement exponential backoff:

Retry with exponential backoff

async function createSessionWithRetry(params: any, maxRetries = 3) {
  let lastError;
  
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await facesign.sessions.create(params);
    } catch (error) {
      lastError = error;
      
      // Don't retry client errors (4xx) except rate limits
      if (error.statusCode >= 400 && error.statusCode < 500 && error.statusCode !== 429) {
        throw error;
      }
      
      // Calculate delay with exponential backoff
      const delay = Math.min(1000 * Math.pow(2, i), 10000);
      
      // Use Retry-After header if available
      if (error.headers && error.headers['retry-after']) {
        const retryAfter = parseInt(error.headers['retry-after']) * 1000;
        await new Promise(resolve => setTimeout(resolve, retryAfter));
      } else {
        await new Promise(resolve => setTimeout(resolve, delay));
      }
    }
  }
  
  throw lastError;
}

Idempotency

To safely retry requests without accidentally performing the same operation twice, use idempotency keys:

Using idempotency keys

const session = await facesign.sessions.create({
  mode: 'redirect',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
}, {
  idempotencyKey: 'unique-key-for-this-request',
});

Best practices

Always handle errors gracefully - Don't let API errors crash your application
Log errors for debugging - Include request IDs for easier troubleshooting
Implement retry logic - Use exponential backoff for transient errors
Respect rate limits - Monitor your usage and implement proper throttling
Use idempotency keys - Prevent duplicate operations when retrying
Show user-friendly messages - Don't expose technical error details to end users

Getting help

If you encounter persistent errors:

Check the API status page for any ongoing issues
Review your request parameters against the API documentation
Contact support with the request ID from the error response

Review authentication

Set up webhooks

Learn about rate limits