Skip to main content

​
Common Errors

Validation failures on the Applications API are returned synchronously as 422 responses with an invalid_parameters array naming the fields that failed. The patterns below are the ones partners hit most often. For the complete rule set, see Validation Rules and Errors.
Symptom: POST /v0/applications with status: declined returns 422.Cause: details.adverse_action_notice is required when the status is declined, and the object is all-or-nothing — delivered_at, reason, and delivery_method must all be present.Fix: deliver the notice per your Reg B process, then submit the application with the completed object. Declines and cancels must be reported even though no account is created for them — skipping them is a fair lending compliance gap, not a shortcut.
Symptom: 422 on status: approved, often with an error message mentioning “credit products” even though your product is not a credit product.Causes:
  • details.credit.limit, details.credit.max_limit, and details.credit.underwriting_grade are required on approval. underwriting_grade is also required on declines.
  • The details.credit object itself is required on every application, and is_secured, is_mla, and currency are required within it — whatever the status.
  • None of these rules inspect product type, despite what the error text says. A non-credit product still needs them.
  • limit cannot exceed max_limit.
  • If details.credit.report is included, pulled_at and source are always required, and you must supply exactly one of score (300–850) or non_score_value (unestablished or frozen). Supplying both, or neither, fails.
Fix: complete the credit object per Validation Rules and resubmit.
Symptom: 422 on documents with the reason Documents do not conform to schema specification, on a payload that looks complete. The error names the array, not the entry that failed, so you have to check every entry.Cause: every document type is either a consent or a disclosure, and that determines which timestamp is required. Consent types — esign_agreement, credit_pull_consent, consent_to_link_account, consent_to_link_hsa, negative_option_consent — require consented_at. Every other type is a disclosure and requires displayed_at. document_id and type are always required.Fix: match the timestamp to the type. If you’re mapping from an internal document model, check that the mapping does not send displayed_at for consents by default.
Symptom: 422 naming a field under entities.Likely causes:
  • An entity_id does not resolve to an existing entity.
  • The entity exists but does not meet the data requirements for the role it is being used in.
  • account_holders mixes an individual with a business or sole proprietor. That combination is not permitted; business and sole proprietor entities may be combined with each other.
  • A commercial application is missing authorized_signers, which are required when account holders are businesses or sole proprietors.
Note: entity ID resolution and role validation run only when status is approved. A declined or canceled application does not surface those errors, so an entity problem can stay hidden until your first approval. The duplicate-entity checks are the exception and run on every status.How to confirm: GET the entity and inspect the role_details array — an inactive role’s criteria_details names the exact failed checks. See Entity Troubleshooting for how to read them, including the “Understand Indirect Failures” section on roles that fail because a related child entity failed its own checks.Fix: correct the entity data or the account holder composition, then retry. Using intended_roles on entity creation surfaces these problems before you ever call the Applications API.
Symptom: an application was submitted as approved when the correct outcome was declined, or vice versa.Fix: correct it with PATCH /v0/applications/{id}, supplying the corrected status. Because updates run the same validations as creation, the correction must also carry whatever the new status requires — a correction to declined needs a complete details.adverse_action_notice object.
Symptom: lookups by your own identifier return an error or 404.Cause: GET /v0/applications/{id} takes the server-generated application_* ID only. Your identifier is queried as GET /v0/applications?client_application_id=…, the filtered form of the collection.Fix: use the query-parameter form for client-assigned IDs, and store the application_* ID from the create response for direct retrieval. Note that client_application_id is present only on applications created via file upload — applications created through the API are identified solely by their server-generated ID.
Still stuck? Contact your Lead team with the application_id (or client_application_id), the full request payload, and the 422 response body.