Error Handling

Use this page to understand:

• How API errors are structured
• How to use code, message, and doc_url

Error Response Body

Field	Type	Description
errors	array	List of one or more error objects.
errors[].code	string	Stable machine-readable code for client handling.
errors[].message	string	Human-readable detail of what failed.
errors[].doc_url	string	Absolute URL to the matching error-code page (domain depends on deployed docs environment).

Error Code Directory

Filter error codes

150 results

Error code	HTTP status	Description
BROKER_USER_ALREADY_EXISTS	409	The Broker-side User already has an identity link.
EMAIL_ALREADY_USED	409	This email address belongs to a user in another Broker organization.
SERVICE_ACCOUNT_ALREADY_EXISTS	409	The Broker already has a Service Account with this display name.
BROKER_ORGANIZATION_NOT_FOUND	404	The Broker has no linked identity-provider organization.
EXTERNAL_USER_ID_ALREADY_USED	409	The external user id is already assigned in this Broker.
LAST_BROKER_ADMINISTRATOR	409	The change would leave the Broker without an active Broker Administrator.
parameter_invalid	400	The request body contains invalid JSON, or a request parameter does not satisfy the expected schema.
email_message_invalid_subject	400	The queued email subject exceeds the entity limit.
queue_email_message_invalid_idempotency_key	400	The queued email idempotency key is blank or invalid.
queue_email_message_internal_template_rendering_failed	400	The internal email template could not be rendered.
DUPLICATE_INSTRUMENT_IN_TARGET_ALLOCATION	422	The same instrument ID appears more than once in a target allocation.
DUPLICATE_INSTRUMENT_IN_SWITCH	422	The same instrument ID appears more than once in a switch.
INVALID_TARGET_ALLOCATION	422	One target-allocation percentage fails validation.
PERCENTAGE_BUY_LEGS_SUM_IS_NOT_10000_BASIS_POINTS	422	The buy legs do not sum to 10000 basis points.
PERCENTAGE_TARGET_ALLOCATION_IS_NOT_10000_BASIS_POINTS	422	The target allocation does not sum to 10000 basis points.
SELF_INVESTMENT_SWITCH_COMPARTMENT_IS_NOT_SELF_INVESTED	422	The compartment is not self-invested.
SELF_INVESTMENT_SWITCH_POSITION_IS_UNKNOWN	422	A sell leg references an unknown current position.
self_investment_switch_share_valuation_is_unknown	400	A switch leg references a fund without a known share valuation.
ATTEMPT_TO_SELL_FULL_POSITION_IN_AMOUNT	422	A full-position sell leg was expressed as an amount.
attempt_to_buy_in_amount_when_selling_full_position	400	A buy leg was expressed as an amount while selling a full position.
LEGS_ARE_NOT_BALANCED	422	The sell and buy legs do not balance.
INSUFFICIENT_FUNDS_IN_PERCENTAGE	422	The percentage sell exceeds the available position.
unauthorized	401	Authentication is missing, invalid, or rejected.
forbidden	403	The authenticated caller lacks permission for the operation.
resource_not_found	404	The requested resource does not exist.
SUBSCRIBER_NOT_FOUND	404	The requested subscriber does not exist.
dek_not_found	404	No active DEK exists for the requested subscriber.
COMPARTMENT_NOT_FOUND	404	The requested compartment does not exist.
COMPARTMENT_ALREADY_SELF_INVESTED	422	The compartment already uses self-investment.
PREMIUM_REQUEST_NOT_FOUND	404	The premium request is unknown.
PREMIUM_REQUEST_COMPARTMENT_MISMATCH	404	The premium request belongs to a different compartment.
DISCRETIONARY_MANAGER_NOT_FOUND	404	The requested discretionary manager does not exist, including a managerId filter on the mandate list.
fund_not_found	404	The requested fund or ISIN does not exist.
MANDATE_NOT_FOUND	404	The requested mandate does not exist.
conflict	409	The request could not be completed because of a state conflict.
BROKER_NAME_ALREADY_USED	409	Authentication cannot use the organization with the requested Broker name.
BROKER_ADMIN_ALREADY_EXISTS	409	The Broker name already exists, or its administrator has another email address.
PARAMETER_INVALID	400	Authentication rejected the Broker provisioning data.
IDEMPOTENCY_KEY_IN_PROGRESS	409	A request with this idempotency key has no result yet.
EMPTY_DOCUMENT	422	The document to certify holds no byte.
DOCUMENT_TOO_LARGE	422	The document to certify holds more than 20 MB.
BLOCKCHAIN_UNAVAILABLE	424	The blockchain network did not answer: the document is not verified yet.
MALFORMED_JSON_DOCUMENT	422	The document to certify or verify is declared as JSON, but it does not parse.
INVALID_TEXT_ENCODING	422	The document to certify or verify is declared as plain text, but it is not valid UTF-8.
CERTIFICATION_NOT_FOUND	404	The certification does not exist.
IDEMPOTENCY_KEY_CONFLICT	409	The idempotency key was already used with a different request payload.
IDEMPOTENCY_KEY_IN_PROGRESS	409	A request with this idempotency key is still in progress.
COMPARTMENT_ALREADY_EXISTS	409	A compartment already uses the generated identifier.
self_investment_target_allocation_compartment_is_not_self_invested	409	The compartment is not self-invested.
SWITCH_ALREADY_EXISTS	409	A switch with the same ID already exists.
target_allocation_already_exists	409	A target allocation with the same ID already exists.
PREMIUM_ALLOCATION_ALREADY_EXISTS	409	An immutable allocation already exists for the premium request.
PREMIUM_ALREADY_INVESTED	409	The single premium was already invested and its allocation is locked.
DISCRETIONARY_MANAGER_ALREADY_EXISTS	422	A discretionary manager already uses the requested name.
MANDATE_ALREADY_EXISTS	422	The discretionary manager already has a mandate with the requested name.
POLICY_STATE_FORBIDS_COMPARTMENT_CREATION	422	The policy state does not permit compartment creation.
POLICY_STATE_FORBIDS_RECONFIGURATION	422	The policy state does not permit compartment reconfiguration.
COMPARTMENT_ARCHIVED	422	The compartment is archived and cannot be reconfigured.
COMPARTMENT_ALREADY_ARCHIVED	422	The compartment has already been archived.
COMPARTMENT_STILL_HOLDS_POSITIONS	422	The compartment still holds post-settlement positions.
LAST_ACTIVE_COMPARTMENT	422	A policy must retain at least one active compartment.
TRANSFER_AMOUNT_REQUIRED	400	The source under mandate requires a total amount.
TRANSFER_FUNDS_REQUIRED	400	The self-invested source requires a nonempty funds array.
SOURCE_COMPARTMENT_NOT_FOUND	404	The source compartment of the transfer does not exist.
TARGET_COMPARTMENT_NOT_FOUND	404	The target compartment of the transfer does not exist.
SOURCE_COMPARTMENT_ARCHIVED	422	The source compartment is archived.
TARGET_COMPARTMENT_ARCHIVED	422	The target compartment is archived.
SAME_SOURCE_AND_TARGET_COMPARTMENT	422	The source compartment and the target compartment are the same.
CROSS_POLICY_TRANSFER	422	The target compartment does not belong to the policy of the source compartment.
POLICY_STATE_FORBIDS_TRANSFER	422	The policy state does not permit a transfer between compartments.
AMOUNT_NOT_APPLICABLE	422	The transfer request has a total `amount` for a self-invested source compartment.
FUNDS_NOT_APPLICABLE	422	A source under mandate requires `amount` and does not accept `funds`.
AMOUNT_EXCEEDS_BALANCE	422	The requested transfer amount exceeds the source compartment valuation.
DUPLICATE_INSTRUMENT_IN_TRANSFER	422	The same instrument is in more than one `funds` entry.
TRANSFER_PENDING	422	A recorded transfer on one of the two compartments is not applied yet.
SOURCE_COMPARTMENT_EMPTY	422	The source compartment holds no settled position.
ORDERS_IN_FLIGHT_ON_COMPARTMENT	422	The source compartment or the target compartment has orders that are not settled.
INSTRUMENT_NOT_HELD	422	The source compartment does not hold an instrument of the request.
NAV_NOT_AVAILABLE	422	An instrument of the request has no NAV.
TRANSFER_CURRENCY_MISMATCH	422	The currency of a `funds` amount is not the currency of the instrument NAV.
FUND_AMOUNT_EXCEEDS_POSITION	422	The amount for an instrument is more than the value of its position.
MANDATE_NOT_APPLICABLE	422	The request uses mandateId with an incompatible management mode.
UNKNOWN_MANAGEMENT_MODE	422	The compartment management mode is not supported.
INSUFFICIENT_FUNDS	422	The sell amount is larger than the current position.
cannot_sell_empty_position	422	A full-position sell targets a position whose current amount is zero.
position_might_be_insufficient_due_to_market_drop_down	422	The switch sells too much of the position to stay safe against market movement.
ALLOCATION_NOT_ALLOWED_FOR_DISCRETIONARY_COMPARTMENT	422	Subscriber allocation is not allowed for a discretionary compartment.
DUPLICATE_INSTRUMENT_IN_ALLOCATION	422	The same instrument appears more than once in a premium allocation.
INVALID_ALLOCATION_AMOUNT	422	A premium-allocation amount is outside 0 to 10000 basis points.
ALLOCATION_AMOUNTS_SUM_IS_NOT_10000_BASIS_POINTS	422	Premium-allocation amounts do not total 10000 basis points.
INSTRUMENT_NOT_ELIGIBLE_FOR_PRODUCT	422	An allocation instrument is not offered by the compartment product.
NO_TARGET_ALLOCATION_FOR_MANDATE	422	The mandate has no target allocation, so the compartment cannot be delegated to it.
unprocessable_content	422	The request body is syntactically valid but violates endpoint-specific business rules.
unsupported_document_type	422	The endpoint does not support the document type (OCR: the requested type; certification: the first bytes of the document, or its declared type).
invalid_file_path	422	The OCR source file storage path is invalid.
invalid_callback_url	422	The OCR callback URL is invalid.
subscriber_already_erased	422	The subscriber DEK has already been destroyed and cannot be reissued.
failed_dependency	424	A required downstream dependency failed to complete the request.
IDENTITY_PROVIDER_UNAVAILABLE	503	The identity provider is temporarily unavailable during authentication or identity provider operations.
database_query_timeout	500	A database query timed out while handling the request.
internal_server_error	500	An unexpected server-side error occurred.
unexpected_error	500	An unexpected server-side error occurred.
invalid_idempotency_key	400	The request idempotency key is invalid.
email_message_not_found	404	The requested queued email message does not exist.
payer_invalid_phone_number	422	The phone number provided for the payer could not be validated.
payer_subscriber_not_found	404	The subscriber referenced when creating a payer does not exist.
payer_not_found	404	The requested payer does not exist.
direct_debit_not_found	404	The requested direct debit does not exist or is not in FAILED status.
TRADE_FILE_NOT_FOUND	404	The requested Execution trade file does not exist.
policy_virtual_iban_not_found	404	The requested policy does not exist, so its virtual IBAN cannot be returned.
POLICY_ACCESS_FORBIDDEN	403	The authenticated broker cannot access the requested Death Settlement policy data.
POLICY_NOT_MANAGED_BY_BROKER	403	The authenticated broker does not manage the requested policy.
POLICY_NOT_FOUND	404	The requested policy does not exist in the bounded context's local projection.
beneficiary_designation_not_found	404	The policy exists but has no current beneficiary designation.
INSURED_NOT_FOUND	404	The policy exists but has no current insured.
unsupported_beneficiary_designation_kind	422	The beneficiary designation kind is unsupported by the MVP contract.
custom_beneficiary_designation_text_empty	422	The custom beneficiary designation text is empty or whitespace-only.
standard_beneficiary_designation_text_provided	422	Text was supplied for a standard beneficiary designation.
beneficiary_designation_change_forbidden	422	The policy lifecycle state no longer permits beneficiary-designation changes.
product_beneficiary_designation_unsupported	422	The policy product does not support a beneficiary designation.
product_not_found	404	The requested Death Settlement product does not exist in the local projection.
standard_beneficiary_designation_not_found	404	The product exists but has no active standard beneficiary designation wording.
suspense_account_transfer_not_found	404	The requested suspense account transfer does not exist.
payer_personal_iban_already_registered	409	The IBAN is already registered for this payer during payer creation.
payer_human_id_generation_failed	500	The system could not generate a human-readable identifier for the new payer.
payer_created_event_store_failed	500	The system could not persist the PayerCreated event.
broker_not_found	404	The broker referenced by the authenticated broker identity does not exist.
broker_not_found_by_payer_id	404	The broker associated with the payer's subscriber could not be found.
personal_iban_not_found	404	The requested personal IBAN does not exist for the payer.
register_payer_personal_iban_unauthorized_country	422	The IBAN's country is not authorized for registration.
register_payer_personal_iban_already_registered	409	The IBAN is already registered for this payer.
callback_url_already_registered_for_broker	409	The callback URL is already registered for this broker.
registration_not_found	404	The broker notification registration does not exist for this broker.
register_payer_personal_iban_event_store_failed	500	Could not persist the event after registering the personal IBAN.
delete_payer_personal_iban_has_premium_request	409	The IBAN is associated with one or more premium requests.
delete_payer_personal_iban_default_iban	409	The IBAN is set as the default IBAN and cannot be deleted.
delete_payer_personal_iban_event_store_failed	500	Could not persist the event after deleting the personal IBAN.
single_premium_request_details_not_found	404	The requested single premium request details were not found.
single_premium_request_not_found	404	The requested single premium request does not exist. Used by repository/internal code, not current premium-scheduling HTTP responses.
single_premium_request_not_pending	404 / 409	The single premium request is no longer in PENDING status.
single_premium_request_compartment_not_found	404	The compartment referenced when creating a single premium request does not exist.
single_premium_request_payer_iban_not_found	404	The payer IBAN referenced when creating a single premium request was not found.
single_premium_request_payer_belongs_to_another_subscriber	422	The payer belongs to a different subscriber.
recurring_premium_request_not_found	404	The requested recurring premium request does not exist.
recurring_premium_request_occurrence_not_found	404	The recurring premium request occurrence was not found.
recurring_premium_request_payer_iban_not_found	404	The payer IBAN was not found when creating a recurring premium request.
recurring_premium_request_payer_belongs_to_another_subscriber	422	The payer belongs to a different subscriber.
recurring_premium_request_invalid_periodicity_unit	400	The periodicity unit is invalid.
recurring_premium_request_invalid_periodicity_value	400	The periodicity value is invalid.
recurring_premium_request_invalid_day_of_month	400	The day of month is invalid.

HTTP Status Code Reference

HTTP status	Meaning in current API behavior
200 OK	Successful cancellation response
201 Created	Resource created successfully
400 Bad Request	Request validation or client input error
401 Unauthorized	Missing or invalid authentication, or unknown identity
403 Forbidden	Authenticated caller lacks required permission or claim
404 Not Found	Referenced entity or request does not exist
409 Conflict	Operation rejected due to state conflict
422 Unprocessable Content	Request is valid JSON but violates business rules
500 Internal Server Error	Unexpected server error