Error Codes

Onboarding & Core Error Code Reference

When validation fails, or when request parameters violate business rules, Harbor returns structured validation errors (422 Unprocessable Entity), state conflicts (409 Conflict), or custom numeric error codes. Use this reference to parse error responses and guide your users on corrective actions.

1. Onboarding & Validation Error Codes

The following numeric error codes are returned in the response body when submitting or updating onboarding data (POST / PATCH / /upgrade endpoints):

HTTP	Code	Meaning	What It Means / Developer Action
`422`	—	Field-level validation failed	One or more payload parameters are invalid. The response contains specific field-level validation errors.
`409`	`2302`	Onboarding in progress	An onboarding is already in progress for this customer. Only one active onboarding is allowed.
`409`	`2303`	Level already approved / Conflict	Target level has already been approved, or `PATCH`/`POST` conflicts with current verified tier.
`409`	`2305`	Action blocked during processing	Tried to call `PATCH` or submit an upgrade while the onboarding status is still `processing`. Wait for processing to complete.
`422`	`2306`	Customer already verified	The customer is already fully KYC/KYB verified and cannot undergo onboarding again.
`422`	`2310`	Ineligible for elevation	The upgrade request does not meet eligibility prerequisites (e.g., attempting to upgrade to Level 3 before Level 2 is verified).
`409`	`2313`	Upgrade cooldown in progress	A Level 3 upgrade request was recently rejected, and the compliance cooldown period is active.
`422`	`2316`	Level 1 US-only violation	Submitting a non-US resident (`residence.country != "US"`) for Level 1 is forbidden.
`422`	`2318`	Upgrade blocked by outstanding RFI	Cannot request an upgrade because the current onboarding is in `action_required` status. Correct existing data first.
`422`	`2319`	Duplicate upgrade in progress	Cannot request an upgrade because another upgrade request is currently being processed.

2. Onboarding Upgrade Conflicts (409 Conflict)

When calling the /upgrade endpoint, if the upgrade request cannot proceed due to the customer's current onboarding state, the API returns a 409 Conflict response with a specific situation or error state:

Situation / Situation Code	Meaning	What It Means / Developer Action
`action_required`	Onboarding action required	The current onboarding level is in `action_required` state. The customer must resolve outstanding requirements using PATCH on the main onboarding endpoint.
`action_required_in_flight`	Upgrade action required	An upgrade is already pending but needs correction. Fix issues by sending a PATCH request.
`processing`	Onboarding in progress	The customer's initial onboarding is still being validated. Wait for initial onboarding to become `verified` first.
`submission_processing`	Upgrade request validating	An upgrade request is already in progress and being validated. Wait for the request to finish.
`submitted`	Upgrade under review	An upgrade request is under manual compliance review. Wait for the compliance team to approve or reject the pending review.
`already_active`	Level already active	No action needed. The customer has already been verified at this level (or higher).
`details`	Prerequisites not met	The upgrade request does not meet the eligibility prerequisites. Read the error details and ensure Level 2 is verified before attempting Level 3.

3. Onboarding Entry Middleware Errors

These errors are thrown by the gateway middleware prior to route processing to protect data scheme integrity:

HTTP	Error Identifier	What It Means / Developer Action
`422`	`individual_route_type_mismatch`	Attempted to submit a Graded Onboarding (v2) individual payload for a customer whose type is `corporate`.
`422`	`kyc_delegated_not_supported`	Graded Onboarding is not supported for Delegated KYC customers.
`422`	`v1_customer_use_v1`	Customer is already on the V1 onboarding scheme (has V1 records/history) and cannot migrate to V2.