Errors
Overview
Orum uses HTTP status codes to indicate the success or failure of your API requests. If an API request fails due to an issue with authentication, authorization, or request validation, Deliver will synchronously return an HTTP status code, error code, and message.
Note:
Some errors cannot be caught synchronously at the time of the API request. The below errors will be sent via webhooks in the status_reasons
object:
- Errors that stem from payment processors: Payment rejections and returns. See transfer status reasons for more information.
- Verification errors: Failure to verify a Person. See person status reasons for more information.
Error Schema and Examples
Synchronous errors contain an error_code
and a message
.
{
"error_code": "missing_first_name",
"message": "First name is required. Accepted values are letters, spaces, hyphens, apostrophes, periods, and diacritics."
}
Authentication and Authorization Errors
Below are the errors caused by failing to include a valid auth token or API key in Deliver request headers.
HTTP status code | Error code | Error message |
---|---|---|
401 | unauthorized | Auth token is missing, invalid or expired. Pass the token received from the /authenticate or /refresh endpoints. To pass the token, send: --header 'Authorization: Bearer {token}'. The auth token expires after one hour. Refresh the token using the /refresh endpoint. |
Token Errors
Errors returned by the /authenticate
and /refresh
endpoints.
HTTP status code | Error code | Error message | Issue |
---|---|---|---|
400 | missing_name | Id or name is required. Pass your API credential id. | Not including your API credential id in your request to the /authenticate endpoint. |
400 | missing_password | Secret is required. Pass your API credential secret. | Not including your API credential secret in your request to the /authenticate endpoint. |
401 | unauthorized | Name/id or secret is invalid. | Passing a API credential id or secret that does not exist or is invalid to the /authenticate endpoint. |
401 | unauthorized | The refresh token has expired. Obtain a new refresh token using the /authenticate endpoint. | Passing an expired refresh token to the /authenticate endpoint. The refresh token is valid for 30 days – after 30 days, obtain a new token using the /authenticate endpoint. |
401 | unauthorized | Refresh token is invalid. Pass the refresh token received from the /authenticate endpoint. | Passing an invalid refresh token to the /refresh endpoint. |
400 | missing_refresh_token | Refresh token is required. Pass the refresh token received from the /authenticate endpoint. | Not including the refresh token in a call to the /refresh endpoint. |
Persons Errors
HTTP status code | Error code | Error message |
---|---|---|
404 | unknown_id | Id is unknown. Pass the Orum-generated id for the person in the id path parameter. |
400 | missing_customer_reference_id | Customer reference id is required. Pass a unique customer reference id. |
400 | missing_customer_reference_id | Customer reference id is required. Pass the customer reference id used when creating the person. |
400 | duplicate_customer_reference_id | Resource already exists with provided customer reference id. Pass a unique customer reference id. |
400 | invalid_customer_reference_id | Customer reference id is invalid. Pass a unique customer reference id with type string. |
400 | invalid_customer_reference_id | Customer reference id is invalid. Pass the customer reference id for the person. |
400 | invalid_customer_reference_id | Customer reference id cannot be changed. |
400 | missing_first_name | First name is required. Accepted values are letters, spaces, hyphens, apostrophes, periods, and diacritics. |
400 | invalid_first_name | First name is invalid. Accepted values are letters, spaces, hyphens, apostrophes, periods, and diacritics. |
400 | invalid_middle_name | Middle name is invalid. Accepted values are letters, spaces, hyphens, apostrophes, periods, and diacritics. |
400 | missing_last_name | Last name is required. Accepted values are letters, spaces, hyphens, apostrophes, periods, and diacritics. |
400 | invalid_last_name | Last name is invalid. Accepted values are letters, spaces, hyphens, apostrophes, periods, and diacritics. |
400 | missing_date_of_birth | Date of birth is required. Valid format is YYYY-MM-DD. |
400 | invalid_date_of_birth | Date of birth is invalid. Valid format is YYYY-MM-DD. |
400 | missing_addresses | Addresses array is required. Provide an address of type “home” for the person. |
400 | invalid_addresses | Addresses array is invalid. Pass an array containing an address object. |
400 | missing_addresses_type | Address type is required. Pass type "home" for a person resource. |
400 | invalid_addresses_type | Address type is invalid. Valid type for person is "home". |
400 | missing_address1 | Address1 is required. |
400 | invalid_address1 | Address1 is invalid. Pass a string value. |
400 | invalid_address2 | Address2 is invalid. Pass a string value. |
400 | missing_city | City is required. |
400 | invalid_city | City is invalid. Pass a string value. |
400 | missing_state | State is required. Pass the two-character state code of the address. |
400 | invalid_state | State is invalid. Pass the two-character state code of the address. |
400 | missing_country | Country is required. Only valid country code is "US". |
400 | invalid_country | Country is invalid. Only valid country code is "US". |
400 | missing_zip5 | Zip5 is required. Expecting a 5-digit numeric zip code. |
400 | invalid_zip5 | Invalid zip5. Expecting a string value of a 5-digit numeric zip code. Example: “10055” |
400 | invalid_contacts | Contacts array is invalid. Pass an array of contact information containing phone and/or email contact types. |
400 | missing_contacts_type | Type field is required. Valid types are "phone" or "email". |
400 | invalid_contacts_type | Type field is invalid. Valid type is "phone" or "email". |
400 | duplicate_contacts_type | Contact types are duplicated. Only one contact for each type "phone” or “email” is allowed. |
400 | invalid_phone_value | Phone number is invalid. Pass a valid 10-digit US phone number. |
400 | missing_contacts_value | Value for contact type is missing. For type “phone”, pass a valid 10-digit US phone number. For type “email”, pass valid email. Example: [email protected] |
400 | invalid_social_security_number | Social security number is invalid. |
400 | invalid_metadata | Metadata must be a valid JSON object. |
Businesses Errors
HTTP status code | Error code | Error message |
---|---|---|
400 | missing_customer_reference_id | Customer reference id is required. Pass a unique customer reference id. |
400 | missing_customer_reference_id | Customer reference id is required. Pass the customer reference id for the business. |
404 | unknown_id | Id is unknown. Pass the Orum-generated id for the business in the id path parameter. |
400 | duplicate_customer_reference_id | Resource already exists with the provided customer reference id. |
400 | invalid_customer_reference_id | Customer reference id is invalid. Pass a string value. |
400 | invalid_customer_reference_id | Customer reference id is invalid. Pass the customer reference id for the business. |
400 | invalid_customer_reference_id | Customer reference cannot be changed. |
400 | missing_legal_name | Legal name is required. Accepted values are alphanumeric characters, spaces, hyphens, apostrophes, periods and diacritics. |
400 | invalid_legal_name | Legal name is invalid. Accepted values are alphanumeric characters, spaces, hyphens, apostrophes, periods and diacritics. |
400 | invalid_business_name | Business name is invalid. Accepted values are alphanumeric characters, spaces, hyphens, apostrophes, periods and diacritics. |
400 | invalid_entity_type | Entity type is invalid. Valid entity type is "sole_proprietorship", "partnership", "limited_liability_partnership", "limited_liability_company", "c_corporation", "s_corporation", "b_corporation", or "nonprofit_corporation". |
400 | missing_tax_id | Tax id is required. Expecting 9-digit numeric id. |
400 | invalid_tax_id | Invalid tax id. Expecting 9-digit numeric id. |
400 | missing_tax_id_type | Tax id type is required. Valid tax id type is "tin" or "ein". |
400 | invalid_tax_id_type | Tax id type is invalid. Valid tax id type is "tin" or "ein". |
400 | invalid_account_holder_name | Account holder name is invalid. Accepted values are letters, spaces, hyphens, apostrophes, periods and diacritics. |
400 | invalid_incorporation_date | Incorporation date is invalid. Expecting format YYYY-MM-DD. |
400 | missing_addresses | Addresses array is required. Provide an address of type “legal” for the business. |
400 | invalid_addresses | Addresses array is invalid. Pass an array containing an address object. |
400 | missing_addresses_type | Address type is required. Pass type "legal" for a business resource. |
400 | invalid_addresses_type | Address type is invalid. Valid type for business is "legal". |
400 | missing_address1 | Address1 is required. |
400 | invalid_address1 | Address1 is invalid. Pass a string value. |
400 | invalid_address2 | Address2 is invalid. Pass a string value. |
400 | missing_city | City is required. |
400 | invalid_city | City is invalid. Pass a string value. |
400 | missing_state | State is required. Pass the two-character state code of the address. |
400 | invalid_state | State is invalid. Pass the two-character state code of the address. |
400 | missing_country | Country is required. Only valid country code is "US". |
400 | invalid_country | Country is invalid. Only valid country code is "US". |
400 | missing_zip5 | Zip5 is required. Expecting a 5-digit numeric zip code. |
400 | invalid_zip5 | Invalid zip5. Expecting a string value of a 5-digit numeric zip code. Example: “10055” |
400 | invalid_contacts | Contacts array is invalid. Pass an array of contact information containing phone, website, and/or email contact types. |
400 | missing_contacts_type | Type field is required. Valid types are "phone", "website" or "email". |
400 | invalid_contacts_type | Type field is invalid. Valid type is "phone", "website" or "email". |
400 | duplicate_contacts_type | Contact types are duplicated. Only one contact for each type “phone”, “website” or “email” is allowed. |
400 | invalid_phone_value | Phone number is invalid. Pass a valid 10-digit US phone number. |
400 | missing_contacts_value | Value for contact type is missing. For type “phone”, pass a valid 10-digit US phone number. For type “website”, pass a website with a valid top-level domain. For type “email”, pass a valid email. Example: [email protected] |
External Account Errors
HTTP status code | Error code | Error message | |
---|---|---|---|
400 | missing_account_reference_id | Account reference id is required. Pass a unique account reference id. | |
400 | missing_account_reference_id | Account reference id is required. Pass the external account’s account reference id. | |
400 | unknown_account_reference_id | Enterprise does not have associated external account. Create an external account for the enterprise. | |
400 | invalid_account_reference_id | Account reference id is invalid. Pass a string value. | |
400 | invalid_account_reference_id | Account reference id is invalid. Pass the account reference id for the external account. | |
404 | unknown_id | Id is unknown. Pass the Orum-generated id for the external account in the id path parameter. | |
400 | duplicate_account_reference_id | Resource already exists with the account reference id. | |
400 | missing_customer_reference_id | Customer reference id for the external account’s associated person or business is required. | |
400 | invalid_customer_reference_id | Customer reference id is invalid. Pass a string value. | |
400 | invalid_customer_reference_id | Unable to find associated person or business by customer reference id. | |
400 | missing_customer_resource_type | Customer resource type is required. Valid customer resource type is “person”, “business” or “enterprise”. | |
400 | invalid_customer_resource_type | Customer resource type is invalid. Valid customer resource type is “person”, “business” or “enterprise”. | |
400 | missing_account_type | Account type is required. Valid account type is "checking" or "savings". | |
400 | invalid_account_type | Account type is invalid. Valid account type is "checking" or "savings". | |
400 | missing_routing_number | Routing number is required. Pass a 9-digit routing number. | |
400 | invalid_routing_number | Routing number is invalid. Pass a 9-digit routing number. | |
400 | missing_account_number | Account number is required. Pass an account number with 17 digits or fewer. | |
400 | invalid_account_number | Account number is invalid. Pass and account number with 17 digits or fewer. | |
400 | missing_account_holder_name | Account holder name is required. | |
400 | invalid_account_holder_name | Account holder name is invalid. Accepted values are letters, spaces, hyphens, apostrophes, periods and diacritics. |
Transfer Errors
HTTP status code | Error code | Error message |
---|---|---|
400 | missing_transfer_reference_id | Transfer reference id is required. Pass a unique transfer reference id. |
400 | invalid_transfer_reference_id | Transfer reference id is invalid. Pass a unique transfer reference id with type string. |
400 | missing_source_and_destination | Source and/or destination is required. To make an account-to-account or deposit transfer, pass both a source and destination object. To make a payout, pass only a destination object. To make a direct debit, pass only a source object. |
400 | missing_source_account_reference_id | Account reference id for source is required. Pass the account reference id for the source external account. |
400 | missing_destination_account_reference_id | Account reference id for destination is required. Pass the account reference id for the destination external account. |
400 | missing_source_customer_reference_id | Customer reference id for source is required. Pass the customer reference id for the person or business associated with the source external account. |
400 | missing_destination_customer_reference_id | Customer reference id for destination is required. For a payouts or A2A use case, pass the customer reference id for the person or business associated with the destination external account. For a deposits use case, pass your enterprise name. |
400 | invalid_source_customer_reference_id | Customer reference id for source is invalid. Pass the customer reference id for the person or business associated with the source external account. |
400 | invalid_source_account_reference_id | Account reference id for source is invalid. Pass the customer reference id for the person or business associated with the source external account. |
400 | invalid_destination_account_reference_id | Account reference id for destination is invalid. Pass the account reference id for the destination external account. |
400 | invalid_destination_customer_reference_id | Customer reference id for destination is invalid. Pass the customer reference id for the person or business associated with the destination external account. |
400 | duplicate_transfer_reference_id | Resource already exists with the transfer reference id. Pass a unique transfer reference id. |
400 | missing_amount | Amount is required. Expecting number greater than zero. |
400 | invalid_amount | Amount is invalid. Expecting number greater than zero. |
400 | missing_currency | Currency is required. Must be “USD”. |
400 | invalid_currency | Currency is invalid. Must be “USD”. |
400 | missing_speed | Speed is required. Expecting "standard", "same_day", or "asap". |
400 | invalid_speed | Speed is invalid. Expecting "standard", "same_day", or "asap". |
400 | invalid_account_statement_descriptor | Account statement descriptor is invalid. |
400 | unknown_enterprise_external_account | Enterprise does not have associated external account in requested environment. Create an external account and pass your enterprise id in customer_reference_id. |
400 | missing_transfer_group_id | Transfer group is required. |
400 | invalid_transfer_group_id | Transfer group ID is invalid. |
400 | invalid_source_account_reference_id | Account reference id source of the transfer does not match the transfer group |
400 | invalid_source_customer_reference_id | Customer reference id source of the transfer does not match the transfer group |
400 | invalid_destination_account_reference_id | Account reference id destination of the transfer does not match the transfer group |
400 | invalid_destination_customer_reference_id | Customer reference id destination of the transfer does not match the transfer group |
Transfer Groups Errors
HTTP status code | Error code | Error message |
---|---|---|
400 | missing_transfer_group_reference_id | Transfer group reference id is required. Pass a unique transfer group reference id. |
400 | missing_source_or_destination | Source or destination is required. Use source to specify that all transfers in this group ultimately come from the same source. Use destination to specify that all transfers in this group ultimately go to the same destination. |
400 | invalid_source_and_destination | Transfer group is invalid. You cannot specify both an ultimate source and an ultimate destination in the same group. |
400 | missing_source_account_reference_id | Account reference id for source is required. Pass the account reference id for the source external account. |
400 | missing_source_customer_reference_id | Customer reference id for destination is required. Pass the customer reference id for the person or business associated with the destination external account. |
400 | invalid_source_account_reference_id | Account reference id for source is invalid. Pass the account reference id for the source external account. |
400 | missing_destination_account_reference_id | Account reference id for destination is required. Pass the account reference id for the destination external account. |
400 | missing_destination_customer_reference_id | Customer reference id for destination is required. Pass the customer reference id for the person or business associated with the destination external account. |
400 | invalid_destination_account_reference_id | Account reference id for destination is invalid. Pass the account reference id for the destination external account. |
404 | unknown_id | Id is unknown. Pass the Orum-generated id for the transfer group in the id path parameter. |
Updated 4 months ago