Error Handling

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

HTTP Status Codes

Code	Description
202	Accepted - Submission recorded and queued for background processing
400	Malformed Request - Body is not a JSON object or is too large
401	Unauthorized - API key missing or invalid
403	Forbidden - Partner account is inactive
429	Too Many Requests - Rate limit exceeded
500	Server Error - Internal server issue

Malformed Requests (400)

Returned when the request body cannot be accepted. The attempt is still recorded and assigned a request_id.

Response Format

{
  "error": "Request body must be a JSON object",
  "data": {
    "request_id": "req_01890a5d-ac96-774b-bcce-b302099a8057"
  }
}

Error	Cause
Request body must be a JSON object	Body was empty, not valid JSON, or not a JSON object
Request body exceeds 65000 bytes	Body is larger than the 65,000 byte limit

Authentication Errors (401 / 403)

{
  "error": "Unauthorized: Invalid API Key"
}

See Authentication for the full list of authentication errors.

Rate Limiting (429)

The endpoint allows 300 requests per minute per IP address. When exceeded, the API responds with 429 and a Retry-After header indicating how many seconds to wait.

1. Honor the Retry-After header before retrying
2. Spread out bulk submissions instead of sending them in a single burst

Server Errors (500)

Server errors indicate an issue on FairFigure's side. A 500 means the submission could not be recorded.

{
  "message": "Server Error"
}

Handling Server Errors

Retry Strategy

A 5xx response means the submission was not accepted, so it is safe to retry. Implement exponential backoff: 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

Validation During Processing

Because submissions are processed asynchronously, field-level validation errors (invalid email, EIN not 9 digits, missing required fields) and duplicate checks are handled during background processing; they are not returned in the HTTP response. To avoid rejected submissions:

• Validate the email format before sending
• Ensure the EIN is exactly 9 digits
• Include all required fields (email, business_name, ein)

If you need the outcome of a specific submission, contact partner support with its request_id.

Best Practices

Practice	Description
Validate Before Sending	Validate email format and EIN length (9 digits) before making API requests
Store Request IDs	Log the request_id from every response for tracking and support inquiries
Retry Only on 429/5xx	A 202 means the submission is durably stored; never re-send it
Log Errors	Keep logs of failed requests for debugging and monitoring