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.
403	forbidden	API key is missing or invalid. Pass your API key in the ‘X-API-Key’ header. Ensure the API key is valid for the environment you are accessing.

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 but not included in the request
400	invalid_transfer_group_id	Transfer group ID is not found
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.