🚨Errors & Troubleshooting

Every error the Issue & Transfer SRR API family can return — HTTP status, exact message, cause, and how to fix it.

This page catalogues every error returned by the Commerce REST endpoints used to issue, transfer and manage SRRs:

• POST /port/api/v1/commerce/srrs — Issue & Transfer

• POST /port/api/v1/commerce/collection — Create Collection

• POST /port/api/v1/commerce/signedUrls — Request Signed URL

• POST /port/api/v1/commerce/fileMetadata — File Information Metadata

Replace <base_url> with the environment you are calling — see URL per environment. All examples below use the JSON response envelope described next.

Response envelope

Errors come back in one of two shapes:

Request-level

A single error for the whole request (bad headers, invalid body, duplicate request, internal error):

{
  "statusCode": 400,
  "message": "Address not found: 0xabc...123"
}

message is either a string or an array of strings (when multiple validation rules fail at once).

Per-SRR (issuance)

Issuance is atomic. In a bulk POST /srrs, if any entry fails, the entire batch is cancelled — no SRR in the request is issued. Fix the failing entry and resubmit the whole payload.

Status code overview

Status	Meaning	Typical causes
400 Bad Request	The request was rejected before/at validation, or an SRR entry failed an issuance check	Invalid metadata, bad address, duplicate request, per-SRR codes
401 Unauthorized	Authentication failed	Missing/invalid commerce-api-key or issuer-address
404 Not Found	A referenced file does not exist in storage	POST /fileMetadata for a file that was never uploaded
500 Internal Server Error	A downstream (Startrail / signing / storage) step failed	Quota/NFC limits, STARTRAIL_ERROR, storage instability

Acceptance ≠ minting. A 201 only means the request was accepted and queued (status: "waiting_for_mining"). Blockchain-level failures (e.g. funds, nonce, gas) happen after acceptance and are reported via the webhook, not in the HTTP response. See Asynchronous (post-acceptance) failures.

Errors by status

401

Returned by all Commerce endpoints when the API-key / issuer headers are missing or do not match.

{ "statusCode": 401, "message": "Missing header" }

{ "statusCode": 401, "message": "API Key is not valid for 0xA6E6a9E20a541680a1D6E1412f5088AefBF58a22" }

Message	Cause	Fix
Missing header	commerce-api-key or issuer-address header absent/empty	Send both headers on every request
API Key is not valid for <address>	The key does not resolve to the supplied issuer-address	Use the API key that belongs to that issuer LUW

400

404

500

Per-SRR issuance error codes

These appear in message.results[*].message for POST /srrs (HTTP 400). Each is tied to the externalId of the failing entry.

Code	Meaning	How to fix
DUPLICATE_METADATA	An SRR with identical metadata already exists for this artist	Change the metadata, or skip — it is already issued
DUPLICATE_CHIP	A chip UID in the request is already attached to another SRR	Remove/replace the duplicated chip UID
INVALID_CHIP	A chip UID is malformed or not accepted	Correct the chip UID value(s)
DUPLICATE_EXTERNAL_ID	The externalId was already used by a previous issuance	Use a fresh, unique externalId
UNKNOWN_ARTIST	artistAddress is not a known Licensed User Wallet	Use a valid artist LUW address
SRR_NOT_CREATED	The SRR could not be created on chain	Retry; contact support if it persists

Because the batch is atomic, a single failed entry fails the whole request. The results[] array tells you which externalId to fix.

Request-level errors (400)

Rejected before issuance begins.

Message	Endpoint(s)	Cause	Fix
<field> is invalid. Check it against the metadata JSON schema. Details: …	/srrs	metadata fails the SRR JSON schema	See Metadata validation
Some of the metadata is not defined	/srrs	A payload[] entry has no metadata	Provide metadata for every entry
Some metadata is failed to be converted: <reason>	/srrs	Metadata could not be upgraded to the current schema	Fix the metadata per <reason>
Address not found: <addresses>	/srrs	issuer-address or a payload[*].artistAddress is not a known LUW	Use valid LUW addresses
File URLs must be Startbahn storage URLs (the finalUrl returned by /commerce/signedUrls) or ipfs:// URLs. Upload the files via /commerce/signedUrls and use the returned finalUrl for: [<externalId>] <field>: <url>	/srrs	A metadata.thumbnailURL, metadata.image, metadata.contractTerms.fileURL or attachmentFiles[*].url points at an external host — see File URLs	Upload the file via /signedUrls and use the returned finalUrl
Metadata file URLs (thumbnailURL, image, contractTerms.fileURL) must be publicly accessible - files in the private bucket cannot be served or published to IPFS. Upload them via /commerce/signedUrls with a public file category (e.g. non_attachment_file) and use the returned finalUrl for: [<externalId>] <field>: <url>	/srrs	A thumbnailURL / image / contractTerms.fileURL points at a file uploaded with a private category (certificate, for_authenticity, installation)	Re-upload with a public category — non_attachment_file (recommended) or artwork — and use that finalUrl
Metadata file(s) not found in storage. Upload them via /commerce/signedUrls and use the returned finalUrl for: [<externalId>] <field>: <url>	/srrs	A thumbnailURL / image / contractTerms.fileURL references a Startbahn URL whose file was never uploaded	Upload first via /signedUrls
Metadata file(s) not ready for IPFS publication (CID still being calculated). Check readiness via /commerce/fileMetadata and retry for: [<externalId>] <field>: <url>	/srrs	The referenced file is uploaded but its IPFS CID is still computing	Poll /fileMetadata until cid is present, then retry
One or more attachment files were not found in storage. Upload them via /commerce/signedUrls before issuing.	/srrs	An attachmentFiles[*].url is not an uploaded file	Upload first via /signedUrls
Attachment hash not ready for <url>. Wait for hash calculation and retry, or check via /commerce/fileMetadata.	/srrs	The file is uploaded but its hash is still computing	Poll /fileMetadata until hash is present, then retry
Duplicate Request Error: Same requestId already logged	/srrs	The requestId was already used for this issuer	Use a new unique requestId (UUID)
Request Content Error: Current request already logged with status <in_progress|successful>	/srrs	An identical payload is already in flight or already succeeded	Do not resubmit; read the result via the subgraph
extension is missing / space is not allowed	/signedUrls, /fileMetadata	filename has no extension or contains a space	Use a filename like cert.pdf with no spaces

Idempotency. Send a unique requestId (UUID) on every POST /srrs. A retried request with the same requestId is safely rejected instead of double-issuing.

NFC tags and quota errors

If you attach NFC/IC tags to SRRs, two allowance checks apply to the issuer LUW.

STARTRAIL_ERROR: LUW missing NFC tag! does not mean a tag is unregistered. It means the number of IC tag UIDs in your request exceeds the LUW's available NFC-tag allowance.

Error	Rule	Notes
Quota limit exceeded!	SRR issuance count exceeds the LUW's quota	Counts SRRs being issued
LUW missing NFC tag!	IC tag UID count exceeds the LUW's NFC-tag allowance	Single request: that entry's tag count. Bulk request: the sum of tag UIDs across all entries in the request

• You do not pre-register individual tag UIDs — they are registered via metadata at issuance. You only need enough NFC-tag allowance on the LUW beforehand.

• In schema v2.2, the IC tag UIDs go in chipUIDs, and startbahnCertICTagUIDs must be supplied with the same values (the two are mutually required). See the recipe and schema:

🧩Request Payloads & RecipesVersion 2.2

Metadata validation errors

metadata is validated against the SRR JSON schema (version 2.0+). Failures return 400 with a message of the form:

payload.<i>.metadata is invalid. Check it against the metadata JSON schema. Details: <detail>. <detail>. …

Common <detail> strings:

Detail	Cause	Fix
should have required property '<prop>'	A required field is missing ($schema, name, title, thumbnailURL, image, medium, yearOfCreation)	Add the field
should NOT have additional properties ({"additionalProperty":"<x>"})	A field not allowed by the schema version was sent (additionalProperties: false)	Remove <x>, or use a schema version that defines it
must be equal to one of the allowed values	An enum value (e.g. size.unit, edition.proofType) is invalid	Use an allowed value
$schema path is invalid, file is not found	$schema points at an unknown schema version	Use a valid $schema URL
$schemaIntegrity does not match $schema digest	$schemaIntegrity hash is wrong	Remove it (not required in v2.2) or set the correct digest
royalty rate is out of the acceptable range of 0 to 100	contractTerms.royaltyRate out of range	Use 0–100

v2.2 gotcha: chipUIDs and startbahnCertICTagUIDs are mutually required — supplying only one fails with should have required property 'chipUIDs' (or startbahnCertICTagUIDs). And if isDigital: true, digitalComponents becomes required.

Asynchronous (post-acceptance) failures

A 201 response (status: "waiting_for_mining") means the request was accepted, not that minting succeeded. Blockchain-send failures surface later via the webhook. Underlying reasons you may see in support/logs:

Reason	Meaning
API account is out of funds	The relayer account needs funding — the transaction is retried automatically
nonce is out of sync	Transient nonce issue — auto-resent
transaction underpriced / replacement underpriced	Gas price too low — auto-resent
gas required exceeds allowance	Transaction would exceed gas limits

Confirm final state via the subgraph or the issue/transfer webhook.

How to decode an error — quick steps

1. Check statusCode → use the overview table.

2. Is message an object with results[]? → it's a per-SRR code; the failing externalId is named.

3. Is message a string/array? → it's a request-level error; fix and resubmit the whole batch.

4. STARTRAIL_ERROR: prefix? → a downstream issue; check for NFC/quota keywords, else retry.

5. Got 201 but no SRR minted? → watch the webhook; see async failures.

Quick reference (for tooling/LLMs)

key	status	shape	meaning
Missing header	401	string	auth header absent
API Key is not valid for <addr>	401	string	key ≠ issuer
DUPLICATE_METADATA	400	per-SRR	metadata already issued for artist
DUPLICATE_CHIP	400	per-SRR	chip UID already used
INVALID_CHIP	400	per-SRR	chip UID malformed
DUPLICATE_EXTERNAL_ID	400	per-SRR	externalId reused
UNKNOWN_ARTIST	400	per-SRR	artistAddress not a LUW
SRR_NOT_CREATED	400	per-SRR	on-chain create failed
… metadata is invalid …	400	string[]	JSON-schema failure
Some of the metadata is not defined	400	string	entry missing metadata
Address not found: <addrs>	400	string	issuer/artist not a LUW
Duplicate Request Error: …	400	string	requestId reused
Request Content Error: …	400	string	identical payload in flight/done
Attachment hash not ready …	400	string	file hash still computing
… attachment files were not found …	400	string	file not uploaded
File URLs must be Startbahn storage URLs …	400	string	external URL in thumbnailURL/image/contractTerms.fileURL/attachmentFiles
Metadata file URLs … must be publicly accessible …	400	string	thumbnailURL/image/contractTerms.fileURL in the private bucket
Metadata file(s) not found in storage …	400	string	metadata file URL never uploaded
Metadata file(s) not ready for IPFS publication …	400	string	file CID still computing
STARTRAIL_ERROR: Quota limit exceeded!	500	string	SRR quota exhausted
STARTRAIL_ERROR: LUW missing NFC tag!	500	string	NFC-tag allowance exceeded
STARTRAIL_ERROR: <msg>	500	string	forwarded downstream failure
UNKNOWN_ERROR	500	string	unclassified
[{ index, filePath }]	404	object[]	files not in storage (/fileMetadata)