Errors

Every operation in the API reference lists the errors it can return. This page is the overview: how to read an error, what to do with each code, and what to send Securitize when you need help.

How an error looks

API errors carry a code. Branch on the HTTP status and the code; message is for humans and can change. Quote correlationId when you contact Securitize support.

{
  "statusCode": 409,
  "code": "external_investor_id_conflict",
  "message": "An investor with externalInvestorId \"acme-1001\" already exists for this partner, and this request does not repeat its create. Use the correction endpoint to change its data.",
  "details": { "investorId": "6aca84e5dc49fe8369dd1da4" },
  "correlationId": "partners-api-d3dcfc7c-a3d0-459e-98a5-9d6f23dcb998"
}

details depends on the error:

a validation error lists every field to fix: [{ "field": "phone.code", "message": "code must contain digits only" }] (on a query parameter, a list of strings);
a conflict carries the existing id: { "investorId": … } or { "keyPartyId": … };
a refused submit names who is short: { "investor": …, "keyParties": [ … ] };
a whitelisting waiting for suitability names what: { "notVerified": ["us", "eu"] };
a tax form of the wrong type lists the forms the investor can receive: { "allowed": ["W-9", "W-8BEN"] };
a W-9 sent as data while the investor has a form on file names that form: { "activeTaxForm": { "taxFormId": …, "formType": "W-8BEN" } };
a W-9 sent as data for an investor subject to backup withholding says why: { "reason": "backup_withholding_not_supported" }.

Gateway errors have no code and no correlationId: the request never reached the API. A 401 ({"error": "invalid_request" | "invalid_token", "error_description": …}) means the bearer token is missing, unknown or expired: get a new one and send the request again. A 403 {"message": "You cannot consume this service"} means your account is not enabled for this API (Sandbox and authentication); a 403 IP address not allowed means the request is outside the API, for example a path outside /investors or a DELETE. A body that is not valid JSON answers 400 without a code either.

What to do

Fix the request and send it again

Status	`code`	Typical cause
`400`	`validation_error`	A field is missing or malformed; `details` lists every one, so fix them together. Includes a missing or placeholder `taxId` or `entityIdNumber`, and a wallet address that does not match its family. On a tax form, a second file, a file in a part not named `file`, or a `content-type` set by hand without its boundary says so in `message`, without `details`
`400`	`invalid_document`	A document’s metadata: unknown `type`, wrong number of files or `side`, or a `mime` that does not match the file. As multipart: a file part that does not belong to the document, an empty file, or a `content-type` set by hand without its boundary. See Documents
`400`	`invalid_include`	An `include` value that does not exist; the message lists the allowed ones
`413`	`payload_too_large`	A document file over 10 MB as JSON or over 20 MB as multipart, a tax form over 10 MB, or a JSON request over about 31 MB
`415`	`mime_not_supported`	A file type the document does not accept, or a request without `content-type: application/json` (on the document routes, also accepted: `multipart/form-data`). On a PDF tax-form upload: a file that is not a PDF, or a body that is not `multipart/form-data`
`422`	`document_rejected`	The image could not be read. Send a better scan
`422`	`tax_form_type_not_allowed`	The tax form does not apply to the investor’s type. Send one of the forms in `details.allowed`. See Send a tax form
`422`	`business_rule_violation`	Well-formed but not allowed here; the message says why. On submit: an individual without an identity document, a key party missing documents, or a company with no person among its key parties. On a wallet: the wallet limit or the risk check. On the DLT test: an investor outside the EEA, or the test is locked. On the suitability or the compact suitability: a verdict under compliance review or not approved (`details.reason`: `suitability_under_review`, `suitability_not_approved`). On the compact suitability: an entity (`details.reason: investor_type_not_supported`). On a W-9 sent as data: an investor subject to backup withholding (`details.reason` `backup_withholding_not_supported`); contact support for that investor

Use what already exists

Status	`code`	What to do
`409`	`external_investor_id_conflict`	You already created this investor: the same `externalInvestorId` with different data, or the same tax or registration identifiers under another id. Use `details.investorId`; correct it with `PUT` if the data changed
`409`	`external_key_party_id_conflict`	You already added this key party with different data. Use `details.keyPartyId`; correct it with `PUT`
`409`	`tax_form_already_active`	The investor already has a tax form in force, and a W-9 sent as data does not replace it. `details.activeTaxForm` names it when it can be read: a `W-9` on an investor you sent no other W-9 is your earlier one, on file; keep its `taxFormId`. For any other form, or no `details`, contact Securitize support to correct or replace it

Wait, or finish a step first

Status	`code`	What to do
`409`	`verification_in_review`	The investor or person is under review and cannot change now. Poll the status
`409`	`verification_already_settled`	It has a verdict and can never change. Read the verdict
`409`	`verification_not_initialised`	A registration for verification did not complete. Send that create again with the same body, then repeat the call
`422`	`investor_not_verified`	Whitelisting waits for the investor’s `status` to be `verified`
`422`	`suitability_not_verified`	Whitelisting waits for the suitability (`us`) and, in the EEA, the DLT test (`eu`); `details.notVerified` names which

Stop and talk to Securitize

Status	`code`	What to do
`403`	`token_not_enabled`	The token is not enabled for your account. Check `tokenAddress`, or ask Securitize to enable it
`409`	`email_conflict`	The email belongs to another investor at Securitize; emails are unique across Securitize. Use the investor’s own address
`409`	`identity_conflict`	This data cannot be used to onboard the investor through the API. Do not retry the same data; contact support with the `correlationId`
`409`	`investor_not_eligible`	This investor cannot be onboarded through the API. Contact support with the `correlationId`
`409`	`investor_type_mismatch`, `verification_refused`	The call cannot be applied to this investor’s verification as it stands. Contact support with the `correlationId`
`409`	`investor_not_owned`	Another party leads this investor’s verification; see limited access
`409`	`wallet_conflict`	The address belongs to another investor. Use another address
`422`	`country_not_allowed`	The token’s issuer does not accept investors from this investor’s country

Not found

Status	`code`	Typical cause
`404`	`investor_not_found`	Wrong id, or the wrong kind of id: every path that names an investor takes Securitize’s `investorId`, not your `externalInvestorId`. Also an investor of the other type on a typed route, or another partner’s investor
`404`	`key_party_not_found`	Wrong `keyPartyId`, or a corporate shareholder addressed through a person route (or the other way round)
`404`	`route_not_found`	No operation matches the method and path, for example a typo in the path or a `PATCH`. The message repeats the method and path received; check them against the API reference

Retry

Status	`code`	What to do
`500`	`internal_error`	Retry with backoff; if it persists, contact support with the `correlationId`. The message is always generic
`502`	`verification_handoff_failed`	Send the same request again: a create with the same body finishes its registration; a document is kept and can be sent again; a submit is safe to repeat
`502`	`file_upload_failed`	Nothing was stored. Send the document or the tax form again
`502`	`tax_form_registration_failed`	On a PDF upload, nothing was attached: send the same request again. On a W-9 sent as data, the form may be on file: send it again, and a `409 tax_form_already_active` naming a `W-9` means it is
`502`	`document_outcome_unknown`	The document was kept; whether verification accepted it is not known. Sending it again is safe
`502`	`whitelist_unavailable`	The whitelisting could not be completed or read. Repeat the same request

What is safe to retry

Call	Repeat with the same request
Create an investor or a key party	Safe. Answers `201` with the same id, and finishes a registration a `502` left incomplete
Correct (`PUT`)	Safe before the record locks
Upload a document	Stores another copy. Repeat only after a refusal or a `502` (see Documents)
Submit	Safe. Anything already handed over comes back `skipped`
Register a wallet, whitelist a wallet	Safe. Answers `201` with the current state
Send the suitability	Safe. Once complete, it changes nothing
Send the compact suitability	Safe. Once `verified`, it changes nothing; a repeat of a `processing` or `rejected` one answers `422` with the reason
Upload a tax form PDF	Safe. Each upload replaces the form on file with the one you send
Send a W-9 as data	Safe. A repeat after a timeout or a `502` answers `201`, or `409 tax_form_already_active` naming the W-9 the first attempt put on file: treat that as done
Send a DLT test attempt	Not safe. Each failed attempt uses one of three

Keep a small state per investor in your own system (created, documented, submitted, verdict) and resume from it after a crash, instead of replaying the whole flow.

A handling pattern

const res = await fetch(url, { method, headers, body });
if (res.ok) return { status: res.status, body: await res.json() };   // 200 can mean "already exists": check the status

const body = await res.json().catch(() => ({}));
if (!body.code) throw new GatewayError(res.status, body.message ?? body.error);   // never reached the API: a 401 needs a new token; otherwise check the path

log.warn({ code: body.code, correlationId: body.correlationId });
switch (body.code) {
  case 'validation_error':
  case 'invalid_document':
    return fixAndResend(body.details);              // a bug in your mapping: fix every field listed
  case 'tax_form_type_not_allowed':
    return chooseAnotherForm(body.details.allowed); // the form does not fit the investor's type
  case 'tax_form_already_active':
    return keepOrEscalate(body.details?.activeTaxForm); // a W-9 you sent is on file; any other form goes to support
  case 'route_not_found':
    throw new Error(body.message);                  // a bug in your client: the method or path does not exist
  case 'external_investor_id_conflict':
  case 'external_key_party_id_conflict':
    return useExisting(body.details);               // the record exists: store its id
  case 'verification_in_review':
    return pollLater();                             // wait for the verdict
  case 'internal_error':
  case 'verification_handoff_failed':
  case 'file_upload_failed':
  case 'document_outcome_unknown':
  case 'whitelist_unavailable':
  case 'tax_form_registration_failed':
    return retryWithBackoff();
  default:
    return escalate(body.code, body.correlationId); // identity_conflict, investor_not_eligible, verification_refused…
}

Getting help

When you contact Securitize support about a response, send:

the correlationId (a gateway error has none: say so);
your externalInvestorId, and the investorId or keyPartyId if you have them;
the method and path, and whether it was sandbox or production;
the statusCode and code you received, and what you expected instead.

Never send your client secret, an access token, a document’s base64 content or an investor’s personal data. The correlationId is enough for Securitize to find the request.

Get started

Guides

Concepts

Help

API reference