> For the complete documentation index, see [llms.txt](https://docs.startrail.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/errors-limits-and-edge-cases.md).

# Errors, limits and edge cases

Every error, every limit and the edge cases of the registered-schema routes — status, code, exact message, cause, fix — per route.

All responses use the envelope `{ "statusCode": <n>, "message": <string | string[]> }`. `message` is an array of strings when request-body validation fails (one string per failing field, named `payload.<index>.<field>` or `payload.<field>`); otherwise a string. The schema-registry routes and `POST /commerce/metadata` answer the same envelope. No commerce response carries an `errorCode` field; the code named in a row below is startrail-api's classification of that message, for reference.

## Message formats

| Format                           | Example                                                                                                                              | Where                                                                                                                                     |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Body validation                  | `payload.0.artistAddress must be a valid Ethereum addresses`                                                                         | Every route, `400`, array                                                                                                                 |
| Schema check at the DTO          | `payload.0.metadata is invalid. Check it against the metadata JSON schema. Details: $schema path is invalid, cid is not found ({}).` | `POST /srrs`, `PUT`; the double space is in the message                                                                                   |
| Schema check in the convert step | `<summary>. Details: <instancePath> <message> (<params>). <instancePath> <message> (<params>).`                                      | Registered schemas, issuance, pin and update; `instancePath` is a JSON pointer such as `/custody/status`, empty for document-level errors |
| Entry naming                     | `payload[<i>]: …`, `metadataBatch[<i>]: …`, `txs[<i>]: …`, `(externalId <id>)`, `SRR <tokenId> on <collectionAddress> …`             | Which entry of a bulk is wrong                                                                                                            |
| Upstream pass-through            | The startrail-api `message`, with its status                                                                                         | Any `400`, `403`, `404`, `409`, `422` startrail-api answers about your request                                                            |
| Downstream failure               | `STARTRAIL_ERROR: <reason>`                                                                                                          | `500` from signing, transport, batch building, subgraph, hashing                                                                          |

## Limits

| Limit                                    | Value                                                                                                                                                                                                                                                          | Where                                                                                                                        | Error                                                                                                                                  |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Metadata document, serialized UTF-8 JSON | **204800 bytes**                                                                                                                                                                                                                                               | Each entry of `POST /srrs`; `POST /metadata`; the new or merged document of `PUT` / `PATCH`; enforced again by startrail-api | `metadata exceeds the maximum size of 204800 bytes (serialized size: <n> bytes)` (`payload[<i>]:` prefix on issuance)                  |
| Request body                             | **20 MB** (`FASTIFY_MAX_REQUEST_SIZE`, default `1024 ** 2 * 20`) on both gogh-api and startrail-api                                                                                                                                                            | Every route                                                                                                                  | Refused by the server before the route runs                                                                                            |
| Entries per `POST /srrs`                 | No maximum enforced; minimum 1; ≤ 250 recommended                                                                                                                                                                                                              | —                                                                                                                            | `payload must contain at least 1 elements`                                                                                             |
| Convert chunk                            | **100** entries per call to startrail-api's convert step; larger payloads are sent in consecutive chunks and indexes are renumbered to the payload                                                                                                             | `POST /srrs`                                                                                                                 | —                                                                                                                                      |
| Entries per `POST /srrs/transfers`       | No maximum enforced; minimum 1                                                                                                                                                                                                                                 | —                                                                                                                            | `payload must contain at least 1 elements`                                                                                             |
| Nesting depth                            | **Not enforced.** Only the byte size above and your schema constrain a document                                                                                                                                                                                | —                                                                                                                            | —                                                                                                                                      |
| Rate limit                               | **None enforced by the API.** Keep one update at a time per record; bulk what you can                                                                                                                                                                          | —                                                                                                                            | —                                                                                                                                      |
| `requestId` replay                       | **No time window.** A `requestId` is unique per `issuer-address` for ever, whatever the earlier status (also after a `4xx`)                                                                                                                                    | `POST /srrs`, `PUT`, `PATCH`, transfers, claim                                                                               | `Duplicate Request Error: Same requestId already logged`                                                                               |
| Content replay                           | **No time window.** Issuance, `PUT`, `PATCH`: refused while an identical body (plus `tokenId` for the update routes) is `in_progress` or `successful` for the issuer. Transfers, claim: refused only while `in_progress`. `POST /metadata`, cancel: not logged |                                                                                                                              | `Request Content Error: Current request already logged with status in_progress` / `… successful`                                       |
| `tokenId` path param                     | 1 … 78 decimal digits                                                                                                                                                                                                                                          | `PUT`, `PATCH`, claim, cancel                                                                                                | `tokenId must be a decimal token id (got "<value>")`                                                                                   |
| Schema search                            | `size` 1 … 100 (default 50), `page` ≥ 1, `query` ≤ 2000 characters                                                                                                                                                                                             | `GET /schema-registry/search`                                                                                                | see [Schema registry](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/schema-registry.md#get-search) |
| `customHistoryId`                        | integer ≥ 1, must exist on chain                                                                                                                                                                                                                               | transfers                                                                                                                    | see [transfers](#post-commerce-srrs-transfers)                                                                                         |

## `POST /commerce/srrs`

Entries on the official schema also answer everything in [Errors & Troubleshooting](https://docs.startrail.io/issue-transfer-api/issue-and-transfer-srr-nft/errors.md). The whole payload is checked before anything is signed; one failure refuses the whole request.

| Status | Code                            | Message                                                                                                                                                                              | When                                                                                                                                                                                                            | What to do                                                                                                                                                 |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | —                               | `Missing header`                                                                                                                                                                     | `commerce-api-key` or `issuer-address` absent                                                                                                                                                                   | Send both                                                                                                                                                  |
| `401`  | —                               | `API Key is not valid for <issuer-address>`                                                                                                                                          | Key does not belong to that LUW                                                                                                                                                                                 | Use the matching key                                                                                                                                       |
| `400`  | —                               | `Some of the metadata is not defined`                                                                                                                                                | An entry has no `metadata`                                                                                                                                                                                      | Add it                                                                                                                                                     |
| `400`  | —                               | `payload.<i>.metadata is invalid. Check it against the metadata JSON schema. Details: $schema path is invalid, cid is not found ({}).`                                               | `ipfs://<cid>` is neither an official CID nor a published registry schema                                                                                                                                       | Resolve the schema on the [registry](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/schema-registry.md)                 |
| `400`  | —                               | `payload.<i>.metadata is invalid. Check it against the metadata JSON schema. Details: $schema path is invalid, file is not found ({}).`                                              | Name form with no published match, a gateway URL, or any other unknown `$schema`                                                                                                                                | Use one of the [three forms](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas.md#the-three-forms-of-the-schema-reference) |
| `400`  | —                               | `payload[<i>]: metadata exceeds the maximum size of 204800 bytes (serialized size: <n> bytes)`                                                                                       | Entry too large                                                                                                                                                                                                 | Shrink; archive history into a pinned document                                                                                                             |
| `400`  | —                               | `attachmentFiles is not supported for metadata on a registry schema (externalId <externalId>)`                                                                                       | `attachmentFiles` with a registered schema                                                                                                                                                                      | Reference files from your own fields by storage URL                                                                                                        |
| `400`  | —                               | `Address not found: <addresses>`                                                                                                                                                     | `issuer-address` or an `artistAddress` is not a LUW                                                                                                                                                             | Use LUW addresses                                                                                                                                          |
| `400`  | `METADATA_VALIDATION_FAILED`    | `Some metadata is failed to be converted: metadata failed validation against JSON schema. Details: …`                                                                                | Document breaks the latest published version (pinned form). With more than one entry: `Some metadata is failed to be converted: metadataBatch[<i>]: metadata failed validation against JSON schema. Details: …` | Fix the fields in `Details`                                                                                                                                |
| `400`  | `METADATA_VALIDATION_FAILED`    | `… Details: /$schema names v<old> of <name>; an SRR is issued on the latest version, v<latest>, and the metadata is not valid against it ({"named":"<old>","latest":"<latest>"}). …` | Older version named, document does not fit the latest                                                                                                                                                           | Adapt the document to the latest version                                                                                                                   |
| `400`  | `METADATA_VALIDATION_FAILED`    | `… Details: refers to a file that is not in storage ({"url":"<url>"}).`                                                                                                              | Storage URL, file never uploaded                                                                                                                                                                                | Upload via `/commerce/signedUrls`                                                                                                                          |
| `400`  | `METADATA_VALIDATION_FAILED`    | `… Details: refers to a file whose CID is not calculated yet, retry shortly ({"url":"<url>"}).`                                                                                      | File uploaded, CID pending                                                                                                                                                                                      | Poll `/commerce/fileMetadata`, retry                                                                                                                       |
| `400`  | `API_VALIDATION_ERROR`          | `Some metadata is failed to be converted: $schema path is invalid, cid is not found (ipfs://<cid>)` / `… file is not found (<name> v<version>)`                                      | The schema was unpublished between the DTO check and the convert step                                                                                                                                           | Resolve again                                                                                                                                              |
| `400`  | —                               | `Duplicate Request Error: Same requestId already logged`                                                                                                                             | `requestId` reused                                                                                                                                                                                              | New `requestId`                                                                                                                                            |
| `400`  | —                               | `Request Content Error: Current request already logged with status in_progress` / `… successful`                                                                                     | Identical payload running or done                                                                                                                                                                               | Read the result from the subgraph                                                                                                                          |
| `403`  | `REGISTERED_SCHEMA_NOT_ALLOWED` | `Licensed user <issuer-address> is not enabled for registered metadata schemas`                                                                                                      | Closed release, wallet not enabled                                                                                                                                                                              | [Contact Startbahn](https://startbahn.io/contact)                                                                                                          |
| `400`  | `API_VALIDATION_ERROR`          | `Quota limit exceeded!`                                                                                                                                                              | Issuance quota of the LUW exhausted                                                                                                                                                                             | Top up                                                                                                                                                     |
| `400`  | `API_VALIDATION_ERROR`          | `LUW missing NFC tag!`                                                                                                                                                               | NFC allowance exceeded                                                                                                                                                                                          | Reduce tags or top up                                                                                                                                      |
| `400`  | `API_VALIDATION_ERROR`          | `SRR already exists on chain for artist/metadata combination: […]` / `SRR already on pending issuance for artist/metadata combination: […]`                                          | Same artist and same document already issued or in flight                                                                                                                                                       | Change the document or skip                                                                                                                                |
| `400`  | `API_RESOURCE_NOT_FOUND_ERROR`  | `LicensedUserWallet does not exist for address <address>`                                                                                                                            | startrail-api does not know the LUW                                                                                                                                                                             | Check the address                                                                                                                                          |
| `400`  | `API_VALIDATION_ERROR`          | `<address> is not an owner of collection <address>`                                                                                                                                  | `collectionAddress` not owned by the issuer                                                                                                                                                                     | Use your own collection                                                                                                                                    |
| `400`  | `API_VALIDATION_ERROR`          | `txs[<i>]: <message>`                                                                                                                                                                | One entry of a bulk refused at the typed-data step                                                                                                                                                              | Fix that entry                                                                                                                                             |
| `400`  | `API_VALIDATION_ERROR`          | `batch contains duplicate generalized tx records` / `batch contains duplicate metadata records for createSRRs` / `generalized batch with root <root> already exists`                 | The same entries, or the same batch, sent before                                                                                                                                                                | Change the entries                                                                                                                                         |
| `500`  | —                               | `schema registry resolution failed`                                                                                                                                                  | gogh-api could not read the registry                                                                                                                                                                            | Retry                                                                                                                                                      |
| `500`  | —                               | `STARTRAIL_ERROR: <reason>`                                                                                                                                                          | Signing-api, transport, batch, subgraph failure                                                                                                                                                                 | Retry; contact support with the `requestId`                                                                                                                |
| `500`  | —                               | `<startrail-api message>`, e.g. `Internal Server Error`, `schema document <cid> could not be fetched from the IPFS gateway`                                                          | startrail-api answered 5xx (its `502` for an unreachable schema document arrives as `500`)                                                                                                                      | Retry later                                                                                                                                                |
| `500`  | —                               | `UNKNOWN_ERROR`                                                                                                                                                                      | Unclassified                                                                                                                                                                                                    | Contact support                                                                                                                                            |

A `201` is acceptance; a transaction that reverts on chain afterwards is reported by the [webhook](https://docs.startrail.io/issue-transfer-api/issue-and-transfer-srr-nft/webhook-setup.md), not by this route.

## `POST /commerce/metadata`

| Status | Code                         | Message                                                                                                                                                                                                                                     | When                                       | What to do         |
| ------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ------------------ |
| `401`  | —                            | `Missing header` / `API Key is not valid for <issuer-address>`                                                                                                                                                                              | Headers                                    | Fix the headers    |
| `400`  | —                            | `metadata should not be null or undefined` / `metadata must be an object`                                                                                                                                                                   | Missing or not an object                   | Send an object     |
| `400`  | —                            | `metadata exceeds the maximum size of 204800 bytes (serialized size: <n> bytes)`                                                                                                                                                            | Too large                                  | Shrink             |
| `400`  | —                            | `metadata is invalid. $schema path is invalid, cid is not found (no published registry schema for ipfs://<cid>)` / `metadata is invalid. $schema path is invalid, file is not found (no published registry schema named <name> v<version>)` | Registered reference not published         | Resolve the schema |
| `400`  | `METADATA_VALIDATION_FAILED` | `metadata failed validation against JSON schema. Details: …` (including the storage-file and superseded-version details above)                                                                                                              | Document breaks its schema                 | Fix                |
| `500`  | —                            | `schema registry resolution failed` / `<pinning error>`                                                                                                                                                                                     | Registry or IPFS                           | Retry              |
| `503`  | —                            | `<message>`                                                                                                                                                                                                                                 | Pinning not configured on this environment | Contact support    |

## `PUT` and `PATCH /commerce/srrs/{tokenId}/metadata`

| Status                | Code                            | Message                                                                                                                                                                                                             | When                                                                                                                                            | What to do                                                                                                                                 |
| --------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `401`                 | —                               | `Missing header` / `API Key is not valid for <issuer-address>`                                                                                                                                                      | Headers                                                                                                                                         | Fix the headers                                                                                                                            |
| `400`                 | —                               | `tokenId must be a decimal token id (got "<value>")`                                                                                                                                                                | Path                                                                                                                                            | Digits only                                                                                                                                |
| `400`                 | —                               | `payload.metadata should not be null or undefined` (`PUT`) / `payload must contain at least one of set, append, prepend, insert, schema` (`PATCH`)                                                                  | Empty request                                                                                                                                   | Add the change                                                                                                                             |
| `400`                 | —                               | `payload.collectionAddress must be a valid Ethereum addresses`                                                                                                                                                      | Bad address                                                                                                                                     | Fix                                                                                                                                        |
| `400`                 | —                               | `baseCid must be the metadataCID of the document to patch on top of`                                                                                                                                                | `baseCid` is not a CID                                                                                                                          | Pass the previous `metadataCID`                                                                                                            |
| `400`                 | —                               | `change the schema with payload.schema, not set.$schema`                                                                                                                                                            | `$schema` in `set`                                                                                                                              | Use `schema`                                                                                                                               |
| `400`                 | —                               | `append.<field> must be an array` / `prepend.<field> must be an array` / `insert.<field>.entries must be an array` / `insert.<field> must be an object with index and entries`                                      | Malformed operation                                                                                                                             | Fix the shape                                                                                                                              |
| `400`                 | —                               | `insert.<field>.index must be an integer from 0 to <length>, the current length of <field>`                                                                                                                         | Index out of range                                                                                                                              | 0 … current length                                                                                                                         |
| `400`                 | —                               | `<field> is the target of both <op1> and <op2>: a field takes one array operation per request`                                                                                                                      | Two array operations on one field                                                                                                               | Split into two requests, chaining `baseCid`                                                                                                |
| `400`                 | —                               | `<op>.<field>: the current value of <field> is not an array`                                                                                                                                                        | Target is not an array                                                                                                                          | Use `set`                                                                                                                                  |
| `400`                 | —                               | `metadata exceeds the maximum size of 204800 bytes (serialized size: <n> bytes)`                                                                                                                                    | Result too large (an unbounded `append` cannot grow past it)                                                                                    | Archive old entries                                                                                                                        |
| `400`                 | —                               | `metadata for token <tokenId> is invalid. $schema path is invalid, cid is not found (no published registry schema for ipfs://<cid>)` / `… file is not found (no published registry schema named <name> v<version>)` | Registered `$schema` or `payload.schema` not published                                                                                          | Resolve                                                                                                                                    |
| `400`                 | —                               | `metadata for token <tokenId> is invalid. Details: …`                                                                                                                                                               | Official-schema document invalid (common-js)                                                                                                    | Fix                                                                                                                                        |
| `400`                 | `METADATA_VALIDATION_FAILED`    | `metadata for token <tokenId> is invalid. metadata failed validation against JSON schema. Details: …`                                                                                                               | Registered-schema document invalid in its pinned form — a new field the current version does not allow, a required field removed, an enum value | Fix, or `schema` to a version that allows it                                                                                               |
| `400`                 | `METADATA_VALIDATION_FAILED`    | `… Details: refers to a file that is not in storage ({"url":"<url>"}).` / `… refers to a file whose CID is not calculated yet, retry shortly ({"url":"<url>"}).`                                                    | Storage URL                                                                                                                                     | Upload / wait                                                                                                                              |
| `400`                 | —                               | File URL messages of the official schema                                                                                                                                                                            | Official schema only                                                                                                                            | See [Errors & Troubleshooting](https://docs.startrail.io/issue-transfer-api/issue-and-transfer-srr-nft/errors.md#request-level-errors-400) |
| `400`                 | —                               | `Duplicate Request Error: Same requestId already logged`                                                                                                                                                            | `requestId` reused                                                                                                                              | New `requestId`                                                                                                                            |
| `400`                 | —                               | `Request Content Error: Current request already logged with status in_progress` / `… successful`                                                                                                                    | Same change on the same token running or done                                                                                                   | Read the current document                                                                                                                  |
| `403`                 | `REGISTERED_SCHEMA_NOT_ALLOWED` | `Licensed user <issuer-address> is not enabled for registered metadata schemas`                                                                                                                                     | Closed release                                                                                                                                  | Contact Startbahn                                                                                                                          |
| `404`                 | —                               | `SRR <tokenId> not found or has no metadata` / `SRR <tokenId> on <collectionAddress> not found or has no metadata`                                                                                                  | Unknown token, wrong or missing `collectionAddress`, not indexed yet                                                                            | Check the address; poll the read route first                                                                                               |
| `404`                 | —                               | `no metadata document for <cid>: <reason>`                                                                                                                                                                          | `baseCid` resolves to nothing (wrong CID, legacy digest)                                                                                        | Read `metadataDigest` from the read route and rebuild                                                                                      |
| `400` / `403` / `404` | pass-through                    | `<startrail-api message>`                                                                                                                                                                                           | Permission (not issuer, artist or collection owner), `Token <id>, Collection <address> not found`, duplicate request on its side                | Act on the message                                                                                                                         |
| `500`                 | —                               | `STARTRAIL_ERROR: current metadata <cid> is not a JSON object`                                                                                                                                                      | The current document is not an object                                                                                                           | Contact support                                                                                                                            |
| `500`                 | —                               | `STARTRAIL_ERROR: <reason>` / `schema registry resolution failed` / `<startrail-api message>`                                                                                                                       | Signing, transport, registry, startrail-api 5xx                                                                                                 | Retry                                                                                                                                      |
| `204`                 | —                               | —                                                                                                                                                                                                                   | Nothing changes; not an error                                                                                                                   | —                                                                                                                                          |

### `baseCid` stale or not current

Not detected. gogh-api patches on top of whatever `baseCid` names and compares the result with that same CID for the `204` check; it never compares `baseCid` with the SRR's current `metadataDigest`. A stale `baseCid` therefore yields a `200` and a new version that lacks the changes made in between. The only guard is yours: one update at a time per record, `baseCid` = the `metadataCID` of the last `200`.

## `POST /commerce/srrs/transfers`, claim, cancel

The full table, including every pre-check, is on [Transfers → Failures](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/transfers.md#failures). Summary by category:

| Status        | Code                           | Message                                                                                                                                                          | When                                                                       | What to do                                                     |
| ------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `401`         | —                              | `Missing header` / `API Key is not valid for <issuer-address>`                                                                                                   | Headers                                                                    | Fix the headers                                                |
| `400`         | —                              | One class-validator message per field (`to` exclusivity, address, email, hash, `transferType`, `customHistoryId`, empty payload)                                 | Body                                                                       | Fix the field                                                  |
| `400`         | —                              | `SRR <tokenId> appears more than once in the payload`                                                                                                            | Duplicate token                                                            | Remove it                                                      |
| `400`         | —                              | `customHistoryId <id> of SRR <tokenId> does not exist on chain`                                                                                                  | Unknown custom history (bulk and single, checked by gogh-api)              | Use an existing id                                             |
| `404`         | —                              | `SRR <tokenId> not found`                                                                                                                                        | Unknown token or wrong collection                                          | Check `collectionAddress`                                      |
| `403`         | —                              | `SRR <tokenId> is owned by <owner>, not by the issuer <issuer-address>` / `SRR <tokenId> is neither owned nor issued by <issuer-address>`                        | Not the owner (transfer, cancel) / neither owner nor issuer (claim)        | —                                                              |
| `409`         | —                              | `SRR <tokenId> already has a pending transfer; cancel it first (DELETE /commerce/srrs/{tokenId}/transfers/pending)`                                              | Pending reservation                                                        | Cancel or claim it                                             |
| `409`         | —                              | `SRR <tokenId> has no pending transfer to claim` / `… to cancel`                                                                                                 | Nothing pending                                                            | —                                                              |
| `400`         | —                              | `SRR <tokenId> has lockExternalTransfer set; a direct transfer to an address would revert on chain. Transfer it by email or revealHash (commit/reveal) instead.` | Locked SRR                                                                 | Reserve instead                                                |
| `400`         | —                              | `the preimage does not match the pending transfer of SRR <tokenId>` / `the revealHash does not match …`                                                          | Wrong secret                                                               | Use the secret of the reservation                              |
| `400`         | —                              | `Duplicate Request Error …` / `Request Content Error: Current request already logged with status in_progress`                                                    | Replay                                                                     | New `requestId`; wait for the running one                      |
| `4xx`         | —                              | `SRR <tokenId> failed: <message>. Already sent and still going to be mined: <tokenIds>`                                                                          | A repeated bulk failed part-way while going out one by one                 | The listed entries are in flight; fix and resend the rest only |
| `404`         | `API_RESOURCE_NOT_FOUND_ERROR` | `Custom history with id (<id>) does not exist on chain`                                                                                                          | startrail-api's own check on a single transfer                             | Use an existing id                                             |
| `400` / `409` | pass-through                   | `<startrail-api message>`                                                                                                                                        | Signing wallet not an owner of the LUW, typed data, nonce, cache reloading | Act on the message; retry a `409`                              |
| `500`         | —                              | `STARTRAIL_ERROR: <reason>` / `<startrail-api message>`                                                                                                          | Downstream                                                                 | Retry                                                          |

## `GET /schema-registry/...`

| Route                | Status | Message                                                                                                                      | When                                                    |
| -------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `search`             | `400`  | `size must be at least 1` / `size must not exceed 100` / `page must be at least 1` / `query must not exceed 2000 characters` | Query parameters                                        |
| `cid/{cid}`          | `404`  | `schema not found`                                                                                                           | Not a CID, unknown, or not published                    |
| `cid/{cid}/document` | `404`  | `schema not found` / `schema document not found`                                                                             | As above / document not readable from the CDN right now |
| `name/{name}`        | `404`  | `schema not found`                                                                                                           | No published release, or none with that `version`       |

## Edge cases

| Case                                               | What happens                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | What to do                                                                                                                                                                                                                                      |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Older schema version moved to latest**           | On issuance, `$schema` naming an older version (`ipfs://<old cid>` or `….v0.2.schema.json`) is validated against the latest published version and pinned with the latest version's CID. If the document is not valid against it, `400` with the `/$schema names v<old> of <name>; an SRR is issued on the latest version, v<latest>, and the metadata is not valid against it` detail first, then the latest version's errors. `PUT` / `PATCH` keep the version the document names | Build documents against the latest version; use `PATCH` `schema` to move an existing record                                                                                                                                                     |
| **Documents without `title` or `name`**            | The registry's `title`, `name` and `version` belong to the record, not to the schema document. A schema that does not require a `name` field yields SRRs without one; nothing in the API adds a `name`, `image` or `description` to registered-schema metadata                                                                                                                                                                                                                     | Require in your schema what you want every record to carry                                                                                                                                                                                      |
| **Storage URL for a missing file**                 | On a registered schema any string that is a `finalUrl` is resolved during the convert step; a file that was never uploaded gives `refers to a file that is not in storage`, one whose CID is pending gives `refers to a file whose CID is not calculated yet, retry shortly`. Both are `400`, nothing is issued. URLs on other hosts are not resolved and are kept as they are; whether they pass is up to your schema                                                             | Upload first, poll `/commerce/fileMetadata` until `cid` is present                                                                                                                                                                              |
| **Gateway URL in `$schema`**                       | `https://cdn.startrail.io/ipfs/<cid>` is not a schema reference: `$schema path is invalid, file is not found`                                                                                                                                                                                                                                                                                                                                                                      | Use `ipfs://<cid>`                                                                                                                                                                                                                              |
| **Collection vs shared-registry reads and writes** | An SRR on a collection is only found with its `collectionAddress`: omit it and the update, transfer, claim and cancel routes answer `404` (`SRR <tokenId> not found …`), the read route `GET /collection/{collectionAddress}/srr/{tokenId}` answers `404` `SRR not found: <collectionAddress>/<tokenId>`. The shared registry has no collection address: omit the field on writes and read with the deprecated `GET /srr/{tokenId}` or the subgraph                                | Store `collectionAddress` with every `tokenId`                                                                                                                                                                                                  |
| **Subgraph lag on the read-back**                  | `201` / `200` means the transaction was sent. The subgraph indexes it a few seconds to about a minute later; until then the read route answers `404` for a new SRR, or the old `metadataDigest` / `ownerAddress` / `transferCommitment` after an update or transfer. `PATCH` without `baseCid` reads the subgraph's CID, so a patch right after another one can start from the old document                                                                                        | Poll `GET /collection/{collectionAddress}/srr/{tokenId}` every few seconds until the field equals the value the write returned; chain `baseCid` instead of relying on the subgraph between patches; use the webhooks for issuance and transfers |
| **`204` on update**                                | A `PUT` with the current document, or a `PATCH` whose result equals the base document, changes nothing: no pin, no transaction, no history entry                                                                                                                                                                                                                                                                                                                                   | Treat it as success with no new version                                                                                                                                                                                                         |
| **Repeated bulk transfer**                         | The same entries sent again cannot reuse their batch root; gogh-api sends them one by one and each result carries a `txReceiptId`                                                                                                                                                                                                                                                                                                                                                  | Nothing; read the per-entry results                                                                                                                                                                                                             |
| **Retry after a timeout**                          | Resend with the **same** `requestId`: if the first request went through you get `Duplicate Request Error` instead of a second issuance; if it did not, it runs now                                                                                                                                                                                                                                                                                                                 | Never generate a new `requestId` for a retry of an unanswered request                                                                                                                                                                           |
| **Retry after a `4xx`**                            | The `requestId` is burnt even though nothing happened; the content is not                                                                                                                                                                                                                                                                                                                                                                                                          | Fix the request and send it with a new `requestId`                                                                                                                                                                                              |
| **Transaction reverts after acceptance**           | Not an HTTP error. Issuance: the webhook reports it. Transfers: `ownerAddress` / `transferCommitment` stay unchanged                                                                                                                                                                                                                                                                                                                                                               | Poll or wait for the webhook before telling your user it is done                                                                                                                                                                                |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/errors-limits-and-edge-cases.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
