Error Codes Reference
This page provides a complete reference of all error codes returned by the relay Experian Integration API. When errors occur, the API returns structured responses with error codes, HTTP status codes, and descriptive messages to help you diagnose and resolve issues.
When contacting relay support about an error, include the error code, HTTP status, and any PID error code from the response. PID refers to Precise ID, the identity verification system used by Experian.
HTTP Status Codes
These are the standard HTTP status codes returned by the API:
| Condition | HTTP Status |
|---|---|
| Successful processing | 200 OK |
| Client input errors (invalid data) | 400 Bad Request |
| Authentication failures | 401 Unauthorized |
| Payment required (prepaid credit balance exhausted, or — Consumer API only — renter payment not completed) | 402 Payment Required |
| File condition errors (frozen profiles, alert list hits) | 422 Unprocessable Entity |
| relay backend exceptions | 500 Internal Server Error |
| Application temporarily unavailable | 503 Service Unavailable |
| Timeouts (session/layer timeouts) | 504 Gateway Timeout |
Billing Error Codes
Returned when an account on the prepaid credit billing model has an exhausted balance. See the API Billing section, the SDK Billing guide, the API Billing Technical Addendum, and the SDK Billing Technical Addendum for handling guidance, or Billing: What's Changing for a plain-language overview.
| Error Code | HTTP Status | Error Message | Cause |
|---|---|---|---|
| PAYMENT_REQUIRED | 402 | "Your credit balance is $0. Please purchase credits to resume service." | Prepaid credit balance exhausted. Deterministic — do not retry; add credits to resume. |
relay Error Codes (Comprehensive Table)
| Endpoint | Error Code | HTTP Status | Error Message | Cause |
|---|---|---|---|---|
| ALL | 1001 | 500 | "Internal error. {details}" | API exception not matching other codes |
| ALL | 1004 | 500 | "Invalid Request" | Improperly formed API request |
| Multiple auth and report endpoints | 1010 | 500 | "User not found. Token: {0}, User ID: {1}, Company ID: {2}" | User not found in Oracle using User Token |
| POST /organizations/{organizationId} | 1999 | 422 | "Match on Alert List" | Consumer alert match in Reseller DB when retrieving questions |
| POST /organizations/{organizationId}/kba | 1999 | 422 | "Match on Alert List" | Consumer alert match when answering questions |
| ANY | 2004 | 422 | "Invalid product required" | Product inactive, not open to sell, or not for pulling reports |
| Report retrieval endpoints | 2801 | 500 | "Invalid userToken or transactionID" | Transaction ID and userToken mismatch |
| Report retrieval endpoints | 2802 | 422 | "Report Expired" | Report expired (30+ days after pull) |
| Report sharing endpoints | 2802 | 422 | "Report Expired" | Shared report expired (30+ days after share) |
| Authentication endpoints | 2000 | 503 | "Authentication Service unavailable. PID Error Code: {0}" | PID unavailable (error codes 258, 259, 304, 324, 352, 358, 362 or exception) |
| Authentication endpoints | 2001 | 422 | "Auth General Error. PID Error Code: {0}" | PID error codes 313, 323, 720 |
| Authentication endpoints | 2002 | 400 | "Invalid Parameter. PID Error Code: {0}" | PID error code 708 |
| POST /organizations/{organizationId} | 2010 | 422 | "Minor Consumer" | PID error code 10 |
| Registration and KBA endpoints | 2013 | 400 | "Format Error" | PID error code 13 |
| POST /organizations/{organizationId} | 2018 | 422 | "Reported as Fraud" | PID error code 18 |
| POST /organizations/{organizationId} | 2045 | 400 | "Invalid Surname" | PID error code 45 or 106 |
| POST /organizations/{organizationId} | 2049 | 400 | "Invalid Zipcode" | PID error code 49 |
| POST /organizations/{organizationId} | 2092 | 400 | "State legislation requires match on more identification information" | PID error code 92 |
| POST /organizations/{organizationId} | 2403 | 400 | "SSN Required" | PID error code 403 |
| POST /organizations/{organizationId} | 2404 | 400 | "Generation Code Required" | PID error code 404 |
| POST /organizations/{organizationId} | 2405 | 400 | "Year of Birth Required" | PID error code 405 |
| POST /organizations/{organizationId} | 2406 | 400 | "Middle Name Required" | PID error code 406 |
| Registration and KBA endpoints | 2407 | 400 | "Unable to Standardize Address" | PID error code 407 |
| Registration and KBA endpoints | 2500 | 504 | "Authentication Session Expired" | PID session timeout, service timeout, or error code 710 |
| Registration and KBA endpoints | 2501 | 422 | "Exceeded limit of Authentication attempted" | No questions returned due to excessive use (KBAResultCode=2) |
| Registration and KBA endpoints | 2502 | 401 | "Failed Authentication. PID Error Code: {0}" | PID incorrect answers |
| Registration and KBA endpoints | 2503 | 422 | "Match on U.S. Department of the Treasury Office of Foreign Assets Control list. PID Error Code: {0}" | OFAC result in (7, 8) |
| POST /organizations/{organizationId} | 2627 | 400 | "Invalid Street Address" | PID error code 627 |
| Authentication endpoints | 3001 | 500 | "Unable to retrieve identity questions. Please verify your information and try again. PID Error Code: {0}" | No questions returned by PID |
| Authentication endpoints | 3001 | 503 | N/A | PID error code 720 |
| Authentication endpoints | 3002 | 401 | "User is already verified" | User already PID authenticated |
| Authentication endpoints | 3008 | 401 | "Unable to verify identity. Please check the answers submitted and try again" | PID incorrect answers |
| Authentication endpoints | 3009 | 504 | "Your identity verification session has expired." | PID session not valid |
| Authentication endpoints | 3011 | 504 | "Unable to verify user's identity at this time. Please try again later" | PID session invalid or invalid response |
| Linking and registration endpoints | 3012 | 500 | "Unable to retrieve identity questions. Please verify your information and try again" | Subcode not found in SSO configuration |
| Authentication endpoints | 3014 | 422 | "No Record Found" | No record found |
| POST /organizations/{organizationId} | 3015 | 422 | "Authentication Failed" | P4C authentication failed |
| ALL | 3901 | 422 | "Consumer reported as deceased" | Consumer deceased (PID Score = 9001) |
| ALL | 7001 | 401 | "Unauthorized Request" | SSO user not provided or no company associated |
| ALL | 7002 | 500 | "SSO security violation missing product {0} for username {1}" | No valid SSO product name |
| ALL | 7004 | 500 | "SSO security violation missing role {0} for username {1}" | No valid SSO user role |
| Registration and linking endpoints | 9001 | 500 | "Company not properly configured in EWACS" | No Subcode in SSO |
| Registration and linking endpoints | 9002 | 500 | "Company not properly configured in CustomerMaster database" | No subcode in Customer Master |
| Registration and linking endpoints | 9003 | 500 | "Unable to retrieve CustomerMaster Subscription data" | Empty or invalid subscription data response |
| Registration and linking endpoints | 9004 | 500 | "Unable to build CreditReport inquiry" | Error pulling or parsing credit report |
| Registration and linking endpoints | 9005 | 422 | "Service unavailable" | File One connection error |
| Registration and linking endpoints | 9006 | 400 | "Sharing User not found. Please check User Token. Token: {0}" | Consumer's user not found |
| POST /renters/{renterId} | 9007 | 400 | "Viewer User not found. Please check User Token. Viewer Token: {0}" | Consumer's user not found |
| Multiple report endpoints | 9008 | 500 | "Unable to get valid users for your company. Please, verify tokens. Company ID: {0}, User ID: {1}, Viewer ID: {2}" | User company doesn't match SSO |
| Report linking endpoints | 9009 | 400 | "Invalid Sharing Purpose. Purpose Type ID: {0}" | Sharing purpose not in configured list |
| POST /renters/{renterId} | 9010 | 401 | "User is not authenticated. Please complete authentication process. User ID: {0}" | User not authenticated |
| Report sharing endpoints | 9011 | 401 | "Viewer is not authenticated. Please complete authentication process. Viewer ID: {0}" | Viewer not authenticated |
| Report linking endpoints | 9012 | 500 | "Invalid Transaction Id. User ID: {0}, Transaction ID: {1}" | Transaction not found in Oracle DB |
| Report linking endpoints | 9014 | 422 | "Product not sharable. Product ID: {0}, Transaction ID: {1}" | Product not available for sharing |
| Report sharing endpoints | 9015 | 422 | "Report expired. User ID: {0}, Transaction ID: {1}" | Report shared beyond 60 days |
| Report sharing endpoints | 9016 | 422 | "Report not found. User ID: {0}, Transaction ID: {1}" | Shared report not found |
| Multiple report endpoints | 9110 | 422 | "Consumer is a Minor" | Report file condition |
| Multiple report endpoints | 9116 | 422 | "File Blocked" | Report file condition |
| Multiple report endpoints | 9132 | 422 | "File Locked" | Report file condition |
| Multiple report endpoints | 9193 | 422 | "No record found" | Report file condition |
| Multiple report endpoints | 9999 | 500 | "Eviction search is unavailable. Please try again later." | Backend error |
| POST /renters/{renterId} | 9018 | 422 | "ssn is required when requesting BackgroundData dob is required when requesting BackgroundData" | SSN and DOB required for Background Data |
| POST /renters/{renterId} | 9995 | 422 | "Invalid SSN . Please try again." | Invalid SSN from Criminal Report |
| POST /renters/{renterId} | 9996 | 422 | "Invalid Date of Birth . Please try again ." | Invalid DOB from Criminal Report |
| Multiple report endpoints | 9997 | 500 | "System error . Please try again later." | Criminal Report system error |
| ANY | 9987 | 500 | "An account with CIC is required." | No CIC account found for company |
File One Error Codes (Credit Report)
These error codes are returned by Experian's File One credit reporting system:
| Error Code | HTTP Status | Error Message | Cause |
|---|---|---|---|
| 10015 | 500 | "AMT- AMOUNT FIELD FORMAT ERROR" | File One error code 015 |
| 10019 | 500 | "EMPLOYMENT FIELD FORMAT ERROR" | File One error code 019 |
| 10031 | 500 | "INVALID SUBSCRIBER NUMBER" | File One error code 031 |
| 10037 | 500 | "INVALID YOB" | File One error code 037 |
| 10043 | 500 | "INVALID USE OF QUEST TYPE CODE" | File One error code 043 |
| 10045 | 500 | "INVALID SURNAME" | File One error code 045 |
| 10047 | 400 | "CURRENT HOUSE NUMBER ERROR" | File One error code 047 |
| 10049 | 400 | "CURRENT ZIP CODE ERROR" | File One error code 049 |
| 10053 | 500 | "INVALID SOCIAL SECURITY NUMBER" | File One error code 053 |
| 10054 | 400 | "PREVIOUS HOUSE NUMBER ERROR" | File One error code 054 |
| 10055 | 400 | "INVALID PREVIOUS STREET ADDRESS FIELD" | File One error code 055 |
| 10056 | 400 | "PREVIOUS ZIP CODE ERROR" | File One error code 056 |
| 10061 | 500 | "INVALID GENERATION CODE" | File One error code 061 |
| 10067 | 500 | "SUBSCRIBER NOT ALLOWED TO INQUIRE" | File One error code 067 |
| 10073 | 400 | "ZIP CODE REQUIRED" | File One error code 073 |
| 10092 | 400 | "STATE LEGISLATION REQUIRES MATCH ON MORE IDENTIFICATION INFORMATION" | File One error code 092 |
| 10130 | 500 | "SPOUSE EMPLOYMENT FORMAT ERROR" | File One error code 130 |
| 10139 | 500 | "INVALID SPOUSE SOCIAL SECURITY NUMBER" | File One error code 139 |
| 10173 | 500 | "INVALID INQUIRY TYPE FOR REPORT CODE" | File One error code 173 |
| 10216 | 400 | "FULL ADDRESS REQUIRED TO REQUEST AP/RETAIL" | File One error code 216 |
| 10222 | 500 | "YOUR SUBS ACCESS NO. IS INACTIVE" | File One error code 222 |
| 10402 | 400 | "*** FULL CURRENT ADDRESS REQUIRED TO ACCESS CONSUMERS FILE ***" | File One error code 402 |
| 10403 | 400 | "SS# REQUIRED TO ACCESS CONSUMERS FILE" | File One error code 403 |
| 10404 | 400 | "GENERATION CODE REQUIRED TO ACCESS CONSUMERS FILE" | File One error code 404 |
| 10405 | 400 | "YEAR OF BIRTH REQUIRED TO ACCESS CONSUMERS FILE" | File One error code 405 |
| 10406 | 400 | "MIDDLE NAME REQUIRED TO ACCESS CONSUMERS FILE" | File One error code 406 |
| 10407 | 400 | "UNABLE TO STANDARDIZE CURRENT ADDRESS" | File One error code 407 |
| 10408 | 400 | "ADDRESS FIELD INVALID" | File One error code 408 |
| 10616 | 400 | "INVALID LAST/FIRST/MIDDLE NAME" | File One error code 616 |
| 10621 | 500 | "INVALID SPOUSE NAME" | File One error code 621 |
| 10627 | 400 | "INVALID STREET ADDRESS FIELD" | File One error code 627 |
| 10630 | 400 | "CITY/STATE REQUIRED FOR INQUIRY TYPE H" | File One error code 630 |
| 10631 | 500 | "PRIMARY NAME LINE EXCEEDS MAX SIZE" | File One error code 631 |
| 10632 | 500 | "SPOUSE NAME: LENGTH INVALID" | File One error code 632 |
| 10633 | 500 | "CURR/BILLING ADDRESS LINE EXCEEDS MAX SIZE" | File One error code 633 |
| 10634 | 500 | "PREV/SERVICE ADDRESS LINE EXCEEDS MAX SIZE" | File One error code 634 |
| 10639 | 500 | "INQUIRY TYPE INVALID FOR THIS SUBCODE" | File One error code 639 |
| 10653 | 500 | "*** END-USER IDENTIFICATION REQUIRED ***" | File One error code 653 |
| 10901 | 500 | "INSUFFICIENT DATA SUPPLIED" | File One error code 901 |
| 10936 | 500 | "INQUIRY TYPE / SUBCODE CONFLICT" | File One error code 936 |
| 10945 | 500 | "ORIGINAL CREDITOR EXCEEDS 30 CHARACTERS" | File One error code 945 |
| 10946 | 500 | "ORIGINAL CREDITOR REQUIRED FOR COLLECTION AGENCIES" | File One error code 946 |
Passive Auth Error Codes
These error codes apply to passive authentication endpoints (subset shown for brevity, full list available in source documentation):
| Endpoint | Error Code | HTTP Status | Error Message | Cause |
|---|---|---|---|---|
| Multiple passive auth endpoints | 1001 | 500 | "Internal error. {details}" | API exception not matching other codes |
| Multiple passive auth endpoints | 1004 | 400 | "Invalid Request" | Improperly formed request |
| KBA endpoints | 1004 | 500 | "Invalid Request" | Improperly formed request |
| Multiple passive auth endpoints | 1010 | 500 | "User not found. Token: {0}, User ID: {1}, Company ID: {2}" | User not found in Oracle |
| OTP and KBA endpoints | 1999 | 422 | "Match on Alert List" | Consumer alert match when getting questions |
| Multiple passive auth endpoints | 2000 | 503 | "Authentication Service unavailable. PID Error Code: {0}" | PID unavailable |
| Registration and resend endpoints | 2502 | 401 | "Auth General Error. PID Error Code: {0}" | PID error codes 313, 323, 720 |
| Multiple passive auth endpoints | 2002 | 400 | "Invalid Parameter. PID Error Code: {0}" | PID error code 708 |
| Registration endpoints | 2010 | 422 | "Minor Consumer" | PID error code 10 |
| Multiple passive auth endpoints | 2013 | 400 | "Format Error" | PID error code 13 |
| Registration endpoints | 2018 | 422 | "Reported as Fraud" | PID error code 18 |
| Registration endpoints | 2045 | 400 | "Invalid Surname" | PID error code 45 or 106 |
| Registration endpoints | 2049 | 400 | "Invalid Zipcode" | PID error code 49 |
| Multiple passive auth endpoints | 2092 | 400 | "State legislation requires match on more identification information" | PID error code 92 |
| Multiple passive auth endpoints | 2403 | 400 | "SSN Required" | PID error code 403 |
| Registration endpoints | 2404 | 400 | "Generation Code Required" | PID error code 404 |
| Registration endpoints | 2405 | 400 | "Year of Birth Required" | PID error code 405 |
| Registration endpoints | 2406 | 400 | "Middle Name Required" | PID error code 406 |
| Multiple passive auth endpoints | 2407 | 400 | "Unable to Standardize Address" | PID error code 407 |
| KBA endpoints | 2500 | 504 | "Authentication Session Expired" | PID session timeout or error code 710 |
| KBA endpoints | 2501 | 422 | "Exceeded limit of Authentication attempted" | No questions due to excessive use |
| Multiple passive auth endpoints | 2502 | 401 | "Failed Authentication. PID Error Code: {0}" | PID incorrect answers |
| Multiple passive auth endpoints | 2503 | 422 | "Match on U.S. Department of the Treasury Office of Foreign Assets Control list. PID Error Code: {0}" | OFAC result in (7, 8) |
| Registration endpoints | 2627 | 400 | "Invalid Street Address" | PID error code 627 |
| Registration endpoints | 2633 | 400 | "Address Exceeds Max Length" | PID error code 633 |
| Multiple passive auth endpoints | 2711 | 400 | "End user required" | PID error code 711 |
| Multiple passive auth endpoints | 2709 | 400 | "Invalid UserId or Password" | PID error code 709 |
| OTP and registration endpoints | 3001 | 500 | "Unable to retrieve identity questions. Please verify your information and try again. PID Error Code: {0}" | No questions returned by PID |
| OTP and KBA endpoints | 3002 | 401 | "User is already verified" | User already PID authenticated |
| OTP and KBA endpoints | 3009 | 504 | "Your identity verification session has expired." | PID session not valid |
| OTP and registration endpoints | 3012 | 500 | "Unable to retrieve identity questions. Please verify your information and try again" | Subcode not found |
| Multiple passive auth endpoints | 3015 | 422 | "Authentication Failed" | P4C authentication failed |
| Multiple passive auth endpoints | 3901 | 422 | "Consumer reported as deceased" | Consumer deceased (PID Score = 9001) |
| Registration endpoints | 7001 | 401 | "Unauthorized Request" | SSO user not provided |
Precise ID (PID) Error Codes Reference
PID refers to Precise ID, Experian's identity verification system. These error codes are referenced in relay error messages:
| Code | Description |
|---|---|
| 10 | Consumer is a minor |
| 13 | Format error |
| 18 | Information on the inquiry was reported as fraud by the consumer |
| 45 | Invalid surname |
| 49 | Current ZIP Code error |
| 92 | State legislation requires match on more identification information |
| 106 | Invalid surname |
| 258 | One or more requested reports unavailable at this time – Please resubmit later |
| 259 | Components of checkpoint system temporarily unavailable. Please resubmit |
| 304 | "*** NFD temporarily unavailable. Please resubmit ***" (NFD Only product option) |
| 313 | NFD does not process inquiries with a Colorado ZIP Code (NFD Only) |
| 323 | Not all data available for evaluation |
| 324 | Detection service is temporarily unavailable |
| 352 | Precise ID system temporarily unavailable |
| 358 | Fraud Shield unavailable |
| 362 | Credit Reporting temporarily unavailable |
| 403 | SSN required to access consumer's file |
| 404 | Generation code required to access consumer's file |
| 405 | Year of Birth required to access consumer's file |
| 406 | Middle name required to access consumer's file |
| 407 | Unable to standardize current address |
| 627 | Invalid street address field |
| 633 | Current Address exceeds maximum length |
| 708 | Input validation error |
| 709 | Invalid User ID/Password |
| 710 | Session timeout (KIQ product options); may also indicate nonexistent Session ID |
| 711 | End User is required |
| 720 | Other Precise ID system error |
Current REST API Error Codes
The tables above are Experian-originated reference codes (File One, Passive Auth, PID) and integration error codes surfaced through report payloads. The sections below list the codes generated by the current relay services themselves: numeric codes in the REST (X-API-KEY) error envelope, and string codes used by the Embedded SDK, its backing platform API, and the screening session endpoints.
Errors from the REST API (X-API-KEY endpoints — Consumer, IRO End User, PMC End User) are returned in the standard envelope { "payload": null, "errors": [{ "errorCode", "errorOnField", "errorMessage" }] } with these codes:
| Error Code | HTTP Status | Meaning |
|---|---|---|
| 121 | 400 / 413 | Malformed request, request body too large, or an Experian 4xx error passed through |
| 123 | 503 | Experian token service unavailable |
| 130 | 500 | Unhandled internal error |
| 131 | 502 | Upstream Experian transport error or 5xx |
| 138 | 400 | Required field missing or invalid (errorOnField names the field, e.g. tokenExpiration for an expired report) |
| 278 | 404 | Renter not found |
| 285 | 402 | Consumer API only — the renter has not completed their per-transaction Stripe Checkout payment (payload contains {reason: "NO_COMPLETED_PAYMENT", message}). This is the numeric-envelope equivalent of the same condition the Embedded SDK's report view surfaces as string code PAYMENT_REQUIRED (see below) — both mean "this renter hasn't paid for this report," not a prepaid-credit issue |
| 292 | 409 | User already registered |
| 293 | 404 | Agent or organization not found |
| 300 | 423 | User blocked by Experian after repeated failed authentication attempts (message includes the unblock time) |
| 324 | 403 | Missing or invalid X-API-KEY ("Invalid client secret.") |
| 341 | 409 | Account not provisioned for live Experian access — contact relay operations |
The Stripe Integration API uses its own convention where errorCode mirrors the HTTP status (400, 409, 500, 503), except malformed JSON which returns errorCode 121.
Embedded SDK & Platform Error Codes
The Embedded SDK and its backing platform API use string error codes. In the SDK these arrive via the onError mount callback (error.code); stable codes are enumerated on Intellirent.SdkErrorCode.
SDK Codes (onError callback)
| Code | Meaning | recoverable |
|---|---|---|
PAYMENT_REQUIRED | Overloaded across two unrelated HTTP 402 causes on the report view: (1) the TSP account's prepaid credit balance is exhausted, or (2) the specific renter being screened hasn't completed their own per-transaction Stripe Checkout payment for this report. The two are distinguishable only by message text — see Billing | always false — for cause (1), do not retry until credits are added; for cause (2), the fix is the renter completing payment, not a credit top-up |
IFRAME_LOAD_FAILED | The iframe's error event fired while loading | always false |
IFRAME_TIMEOUT | The iframe did not finish loading within 30 seconds | always false |
IFRAME_ERROR | Internal: the iframe element could not be created | always false |
TOKEN_EXCHANGE_FAILED | Initial token-exchange request failed outright (network error, no response) or the response was well-formed JSON with no error.code to use instead | true only for HTTP 5xx |
TOKEN_REFRESH_FAILED | Background token refresh failed for the same reasons as above, before the API returned any structured error | true only for HTTP 5xx |
UNKNOWN_ERROR | Token exchange (or refresh) got a non-2xx response whose body couldn't be parsed as JSON at all | true only for HTTP 5xx |
PAYMENT_REQUIRED is the only one of these enumerated on Intellirent.SdkErrorCode today — match the others as literal strings.
Token exchange codes. When the token-exchange request fails with a structured error body, that body's own error.code is delivered to onError in place of the generic TOKEN_EXCHANGE_FAILED / TOKEN_REFRESH_FAILED / UNKNOWN_ERROR above:
| Code | Meaning |
|---|---|
MISSING_KEY | No X-Publishable-Key header was sent |
INVALID_KEY | The publishable key is malformed, or not recognized for this account |
KEY_INACTIVE | The publishable key exists but has been deactivated |
MISSING_ORIGIN | No Origin header was sent |
ORIGIN_NOT_ALLOWED | The host page's origin is not on the key's allowed-origins list |
RATE_LIMITED | The key exceeded its per-minute request quota |
BILLING_NOT_CONFIGURED | A pk_live_* exchange was rejected because the account has neither a Metronome prepaid customer nor a Stripe connected account configured (pk_test_* keys are exempt). Configure billing via your billing portal or account team before using a live key |
INTERNAL_ERROR | Unexpected server-side error during token exchange |
Verification-flow codes. During the screening view's identity-verification steps (device fingerprinting, OTP, KBA, and — for END_USER — post-verification account enrollment), the embedded view can report these to onError too:
| Code | Meaning | recoverable |
|---|---|---|
FINGERPRINT_SDK_UNAVAILABLE | The device-fingerprinting SDK failed to initialize before submission | false |
FINGERPRINT_SCRIPT_LOAD_FAILED | The device-fingerprinting script failed to load | false |
FINGERPRINT_COLLECTION_FAILED | Device fingerprint data could not be collected in time for submission | false |
AUTH_TOKEN_INVALID | The screening submission has no valid auth token (session expired or was never established) | false |
SCREENING_OTP_RESEND_FAILED | Requesting a new OTP code failed | true |
SCREENING_KBA_QUESTIONS_MISSING | No KBA questions were available to present (stepUp data was corrupted or incomplete) | true |
SYSTEM_INTERNAL_ERROR | END_USER publishable-key generation failed after verification succeeded, or a later enrollment step failed without a code of its own | false |
SYSTEM_CONFIGURATION_ERROR | A TSP user tried to mount view: 'screening' — unsupported for that user type | false |
COMPONENT_RENDER_FAILED | A wizard step failed to render (caught by an internal error boundary) | true |
Submitting the initial screening form, an OTP code, or KBA answers can also deliver onError the exact code that request's own API response carried — i.e. any code from the Screening Session Codes table below (INVALID_OTP, INVALID_KBA, USER_BLOCKED, TOO_MANY_ATTEMPTS, VALIDATION_ERROR, IDENTITY_NOT_FOUND, and the rest), with that table's recoverable value.
Not delivered via onError at all. Two validation failures reject their Promise (or throw synchronously) with a plain Error — message only, no .code — instead of invoking onError:
Intellirent.init(config)throws synchronously ifpublishableKeydoesn't match thepk_(live|test)_<16+ chars>format.sdk.mount(selector, options)'s Promise rejects if a requiredscreening.unitAddressis missing/invalid,screening.applicationFeeis not a positive integer ≤ 1,000,000,screening.endUserTypeis provided but isn't one ofINDEPENDENT_OWNER/REAL_ESTATE_AGENT/PROPERTY_MANAGEMENT,selectormatches no element in the DOM, or a view is already mounted on thissdkinstance (callsdk.unmount()first).
Intellirent.SdkErrorCode also exposes VALIDATION_INVALID_FORMAT and INVALID_PUBLISHABLE_KEY constants, but neither is currently wired to any of these failure paths — treat them as reserved, not as codes you'll actually see.
onError.code is not limited to the codes aboveIntellirent.SdkErrorCode only enumerates the codes the SDK itself generates client-side. Treat it as the stable, typed subset rather than the full set of values onError.code can take, and always code defensively (e.g. a default branch) for values not in the enum.
Report / Sharing Codes (GET /reports/{id}, consent-to-share, revoke-sharing)
| Code | HTTP Status | Meaning |
|---|---|---|
AUTH_UNAUTHORIZED | 401 | Authentication required or token invalid |
AUTH_FORBIDDEN | 403 | Insufficient permissions |
NETWORK_RATE_LIMITED | 429 | Rate limit exceeded (respect the Retry-After header) |
SCREENING_SESSION_NOT_COMPLETED | 400 | Verification must be completed before accessing the report |
SCREENING_NOT_FOUND | 404 | Screening session not found |
SCREENING_REPORT_EXPIRED | 410 | Report access window has expired — re-verify to access |
SCREENING_IDENTITY_NOT_FOUND | 422 | Identity could not be verified with the provided details |
SCREENING_USER_BLOCKED | 403 | User blocked from screening |
SCREENING_TOO_MANY_ATTEMPTS | 429 | Too many failed verification attempts |
PAYMENT_REQUIRED | 402 | Payment required before the report can be accessed |
REPORT_ACCESS_DENIED | 403 | No permission to view this report |
REPORT_SHARING_NOT_FOUND | 403 | No sharing record exists between this report and your account |
REPORT_SHARING_REVOKED | 403 | The consumer revoked sharing of this report with your account |
REPORT_SHARING_ALREADY_REVOKED | 409 | Sharing for this report was already revoked |
REPORT_SHARING_EXPIRED | 403 | The recipient's 24-month report view window has expired, or the consumer has not yet consented to this share |
ACCOUNT_NOT_LIVE | 409 | Account not provisioned for live Experian traffic — see ACCOUNT_NOT_PROVISIONED below for the equivalent code on the screening-session surface |
onError — except PAYMENT_REQUIREDThis table lists the codes a direct API caller of GET /reports/{id} (or the consent-to-share/revoke-sharing endpoints) can receive. If you're using the embedded SDK's report view instead, only PAYMENT_REQUIRED (see SDK Codes above) is ever forwarded to your onError callback. Every other code in this table — REPORT_SHARING_EXPIRED, SCREENING_REPORT_EXPIRED, REPORT_SHARING_NOT_FOUND, REPORT_ACCESS_DENIED, and the rest — is rendered as an in-iframe error state with no onError call to the host page. This is the opposite convention from the Screening Session Codes below, where most codes are forwarded — don't assume the same rule applies here.
An expired report returns 400 (errorCode 138) on the REST API but 410 (SCREENING_REPORT_EXPIRED) on the SDK/platform path. The legacy table above lists 422/2802 for the same condition on the legacy service.
GET /reports/{id}SCREENING_REPORT_EXPIRED and REPORT_SHARING_EXPIRED gate different callers and are never interchangeable:
- Consumer (the report's owner) — governed by the report's own 30-day validity. Lapsed →
SCREENING_REPORT_EXPIRED(410). Re-verifying identity renews this. - End user (a recipient the report was shared with) — governed by that recipient's own 24-month view window, independent of the consumer's 30-day token. Lapsed →
REPORT_SHARING_EXPIRED(403). There is no renewal path for a lapsed share window — request a new report from the applicant instead.
A recipient keeps access after the consumer's 30-day token lapses, as long as their own 24-month window is still open. REPORT_SHARING_EXPIRED also covers a share record the consumer has not yet consented to — distinct from REPORT_SHARING_NOT_FOUND (no share record exists at all).
Screening Session Codes (/screening/* responses)
A third code family, distinct from both tables above: the screening session endpoints — POST /screening/submit, POST /screening/{id}/otp, POST /screening/{id}/otp/resend, POST /screening/{id}/kba — return { "error": { "code", "message", "field"?, "recoverable" } }, where code is one of the values below.
onErrorIf you call the screening endpoints directly (see the direct-API path in Architecture), these are the codes you get back. If you use the embedded SDK instead, the iframe's own built-in UI renders most of these states to the end user directly — but the codes for the screening-submission, OTP, and KBA endpoints specifically are also forwarded to the host page's onError callback verbatim, alongside PAYMENT_REQUIRED and the SDK/verification-flow-specific codes listed under SDK Codes above.
| Code | HTTP Status | Recoverable | Meaning |
|---|---|---|---|
VALIDATION_ERROR | 400 | Yes | Generic request validation failure |
VALIDATION_INVALID_FIELD_FORMAT | 400 | Yes | One or more submitted fields failed the screening provider's own format rules; message is a dynamic, per-field description |
INVALID_ADDRESS | 400 | Yes | Address could not be verified or is undeliverable |
INVALID_SSN | 400 | Yes | Invalid SSN format |
INVALID_DOB | 400 | Yes | Invalid date-of-birth format |
INVALID_OTP | 400 | Yes | Incorrect OTP code |
INVALID_KBA | 400 | Yes | One or more KBA answers were incorrect |
USER_BLOCKED | 423 | No | User blocked after repeated failed attempts |
TOO_MANY_ATTEMPTS | 429 | No | Too many verification attempts |
ALREADY_REGISTERED | 409 | No | User already has a completed screening |
SESSION_EXPIRED | 410 | No | The upstream Experian auth session expired before the OTP/KBA submission could be graded — a stale session resumed long after step-up, or (KBA specifically) one already spent by a prior graded attempt. Start a new verification; the same session cannot be retried |
REPORT_EXPIRED | 410 | Yes | Report has expired (30+ days) — submit a new application |
IDENTITY_NOT_FOUND | 404 | No | Identity could not be verified with the details provided |
MINOR_CONSUMER | 422 | No | Consumer is a minor — report cannot be generated |
PRODUCT_NOT_ENABLED | 422 | No | Requested report product is not enabled for this account |
REPORT_MISSING_FIELD | 400 | Yes | A required field (e.g. SSN) was missing from the report request |
ACCOUNT_NOT_PROVISIONED | 409 | No | Account is not provisioned for live Experian traffic — contact relay support. Same underlying condition as ACCOUNT_NOT_LIVE above, surfaced under a different code on this endpoint family: raised at EIS submission time rather than the earlier pk_live gate. Introduced by IDT-969, which stopped this condition from being masked as ALREADY_REGISTERED and now surfaces it to the client unchanged |
An expired upstream auth session is surfaced as SESSION_EXPIRED rather than collapsed — the embedded form cannot recover without it, since a spent session is only fixable by starting a fresh step-up. Every other internal failure on these endpoints — an Experian-credential failure on relay's side, and any unrecognized upstream error — is deliberately collapsed to a generic INTERNAL_ERROR (HTTP 500) before it reaches your integration, so no other code from this family is ever returned to a caller. The true cause is always available in relay's own logs; contact support with the request timestamp if you need it diagnosed.
Need help? If you encounter an error not listed here or need assistance resolving an error, contact relay integration support with the error code, HTTP status, and any PID error code from your API response.