🚨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 & TransferPOST /port/api/v1/commerce/collection— Create CollectionPOST /port/api/v1/commerce/signedUrls— Request Signed URLPOST /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:
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).
For POST /srrs, issuance problems are reported per payload entry under message.results[], keyed by your externalId:
{
"statusCode": 400,
"message": {
"results": [
{
"status": "failed",
"externalId": "c0456840-5bdf-4375-a6ce-106697b7dfb7",
"message": "DUPLICATE_METADATA"
}
]
}
}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
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
Returned by all Commerce endpoints when the API-key / issuer headers are missing or do not match.
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
Two families: request-level (rejected outright) and per-SRR (message.results[]).
See Request-level errors and Per-SRR codes.
Only from POST /fileMetadata, when one or more requested files do not exist in storage. The body lists the missing files:
Referencing a file that was never uploaded, or whose name/category differs from upload
Upload via /signedUrls first; query with the exact filename + category used at upload
A downstream step failed. The message usually carries a STARTRAIL_ERROR: prefix wrapping the underlying reason.
STARTRAIL_ERROR: Quota limit exceeded!
The issuer LUW's SRR issuance quota is exhausted
Top up the issuance quota for the LUW
STARTRAIL_ERROR: LUW missing NFC tag!
NFC tag UIDs in the request exceed the LUW's NFC-tag allowance — see NFC tag errors
Reduce chips in the request or top up NFC-tag allowance
STARTRAIL_ERROR: <other>
A forwarded Startrail / signing failure
Retry; if it persists contact us with the message
UNKNOWN_ERROR
Unclassified server error
Retry; contact support if persistent
It may happen if the network to bucket storage is not stable.
Transient storage error on /signedUrls or /fileMetadata
Retry the request
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.
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.
<field> is invalid. Check it against the metadata JSON schema. Details: …
/srrs
metadata fails the SRR JSON schema
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.
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
metadataat issuance. You only need enough NFC-tag allowance on the LUW beforehand.In schema v2.2, the IC tag UIDs go in
chipUIDs, andstartbahnCertICTagUIDsmust be supplied with the same values (the two are mutually required). See the recipe and schema:
Metadata validation errors
metadata is validated against the SRR JSON schema (version 2.0+). Failures return 400 with a message of the form:
Common <detail> strings:
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:
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
Check
statusCode→ use the overview table.Is
messagean object withresults[]? → it's a per-SRR code; the failingexternalIdis named.Is
messagea string/array? → it's a request-level error; fix and resubmit the whole batch.STARTRAIL_ERROR:prefix? → a downstream issue; check for NFC/quota keywords, else retry.Got
201but no SRR minted? → watch the webhook; see async failures.
Quick reference (for tooling/LLMs)
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)
Last updated
Was this helpful?