Common Error Codes

Note:

Please contact VeraFi Support if you require more information on specific error codes or if you encounter persistent issues during integration.

The VeraFi API uses a consistent error response structure across all endpoints to help developers quickly identify the cause of a failure and take corrective action. Errors may be triggered by invalid request data, authentication failures, missing parameters, rate limits, or server-side issues. Regardless of the source, the response follows the standard format described below.

Error Response Schema

When an error occurs in the VeraFi API, the response typically includes a detail field describing the issue. Validation errors may also include an array that indicates which fields were missing or invalid.

The standardized response structure is shown below:

{
  "detail": "Invalid request parameters"
}

For validation-specific issues, the API returns an expanded structure:

{
  "detail": [
    {
      "loc": ["body", "email"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

The message content varies based on the error type. Authentication-related failures will indicate invalid tokens or missing credentials, while rate-limited endpoints return descriptive messages about retry availability. For OTP workflows, responses may also include remaining attempts.

This structure allows client applications to programmatically interpret errors and handle them gracefully.

Common Errors

This table lists the most common HTTP errors returned by the VeraFi API, summarizing the associated error code, default message, and recommended resolution steps.

Table 1. Common errors and resolution table
HTTP Code	Error Code	Message	Resolution
400	`INVALID_REQUEST`	Invalid request parameters	Verify the request payload, required fields, and formats. Ensure that all parameters meet validation rules.
401	`UNAUTHORIZED`	Invalid credentials or authentication required	Re-authenticate using a valid token or correct credentials. Confirm that the token is not expired.
403	`FORBIDDEN`	Access denied	Ensure the session token corresponds to a user with access rights. Contact an administrator if additional permissions are required.
404	`NOT_FOUND`	Resource not found	Check the endpoint path, object identifiers, or parameters. Ensure the resource exists and is accessible.
422	`VALIDATION_ERROR`	One or more fields are missing or invalid	Review the detailed validation response to correct missing or incorrectly formatted fields.
429	`RATE_LIMIT_EXCEEDED`	Rate limit exceeded. Please try again later.	Reduce request frequency and retry after the cooldown period. OTP endpoints allow 1 request per 2 minutes.
500	`INTERNAL_ERROR`	Internal server error	Retry the request after some time. If issues persist, contact VeraFi Support with the Request ID or logs.

Error Types Returned by VeraFi

VeraFi commonly returns the following error patterns:

Authentication Errors

Returned when login credentials, OTP codes, or tokens are invalid.

The following are the examples:

"detail":"Invalid credentials or authentication required"
"detail":"Invalid OTP. 2 attempts remaining."

Validation Errors

Errors are returned when required fields are missing or malformed. Structure follows the standard FastAPI-style validation array.

Rate Limit Errors

Primarily triggered by OTP and login endpoints:

1 OTP request per 2 minutes
Authentication endpoints: 5 requests per minute
General API calls: 100 requests per minute per token

Permission and Access Errors: Triggered when users attempt to access resources outside their assigned roles or tenant permissions.