Skip to main content

Error Codes

NFI Clear API uses conventional HTTP response codes and provides detailed error codes in the response body.

HTTP Status Codes

CodeStatusDescription
200OKRequest succeeded
201CreatedResource created successfully
400Bad RequestInvalid request parameters
401UnauthorizedInvalid or missing API key
403ForbiddenInsufficient permissions or subscription issues
404Not FoundResource not found
409ConflictResource already exists or conflict
500Internal Server ErrorServer-side error

API Error Codes

Authentication Errors

CodeHTTPDescription
MISSING_API_KEY401No API key provided
INVALID_API_KEY401API key invalid or doesn’t exist
REVOKED_API_KEY401API key has been revoked
EXPIRED_API_KEY401API key has expired
INSUFFICIENT_PERMISSIONS403API key lacks required permissions

Subscription Errors

CodeHTTPDescription
NO_ACTIVE_SUBSCRIPTION403No active subscription found
LIMIT_EXCEEDED403Monthly verification limit reached

Validation Errors

CodeHTTPDescription
INVALID_SUBJECT_TYPE400subjectType must be “kyc” or “kyb”
MISSING_SUBJECT_REFERENCE400subjectReference is required

Resource Errors

CodeHTTPDescription
VERIFICATION_NOT_FOUND404Verification ID not found
DUPLICATE_SUBJECT_REFERENCE409Active verification already exists

Error Response Format

All errors follow this format:
{
  "success": false,
  "error": "Human-readable error message",
  "code": "ERROR_CODE"
}

Handling Errors

Example Error Handler

const makeRequest = async (url, options) => {
  const response = await fetch(url, options);
  const data = await response.json();
  
  if (!data.success) {
    switch (data.code) {
      case 'NO_ACTIVE_SUBSCRIPTION':
        // Handle subscription issue
        showSubscriptionModal();
        break;
      case 'LIMIT_EXCEEDED':
        // Handle limit exceeded
        showUpgradePrompt();
        break;
      case 'DUPLICATE_SUBJECT_REFERENCE':
        // Use existing verification
        return handleDuplicate(data.data.existingVerificationId);
      default:
        throw new Error(data.error);
    }
  }
  
  return data;
};

Getting Help

If you encounter errors not listed here, contact support with:
  • The error code
  • The request that caused it
  • The timestamp of the request