Error Handling

The FairFigure Ingest API uses standard HTTP status codes to indicate the success or failure of requests.

HTTP Status Codes

Code	Description
200	Success - Application processed successfully
422	Validation Error - Request data is invalid
500	Server Error - Internal server issue

Validation Errors (422)

Validation errors occur when the submitted data doesn't meet requirements.

Response Format

{
  "message": "The given data was invalid.",
  "errors": {
    "field_name": [
      "Error message describing the issue."
    ]
  }
}

Common Validation Errors

Email Errors

Error	Cause
The email has already been taken.	Email is already registered in the system
The email must be a valid email address.	Email format is invalid
The email field is required.	Email was not provided

EIN Errors

Error	Cause
The ein has already been taken.	EIN is already registered
The ein must be 9 digits.	EIN format is invalid
The ein field is required.	EIN was not provided

Business Name Errors

Error	Cause
The business_name field is required.	Business name was not provided

Server Errors (500)

Server errors indicate an issue on FairFigure's side.

{
  "error": "Connection timed out"
}

Handling Server Errors

Retry Strategy

Implement exponential backoff when retrying failed requests. Wait 1 second, then 2, then 4, etc.

1. Log the error for debugging
2. Wait before retrying (use exponential backoff)
3. Retry up to 3 times
4. If still failing, alert your team and contact FairFigure support

Best Practices

Practice	Description
Validate Before Sending	Validate email format and EIN length (9 digits) before making API requests
Handle All Responses	Always check the HTTP status code and handle each case appropriately
Log Errors	Keep logs of failed requests for debugging and monitoring