API errors

By the time you leave this page, you will know how to read any error response from the SealTrust API. You will recognize the code returned, you will decide whether to fix your request or replay it as is, and you will find one precise call in our logs when you write to us.

Read this page in full once, when you are writing your client. After that it serves as a catalog.

#Every error has the same shape

The body of an error response contains a single field: detail. Its value takes three forms, and you must know how to handle all three.

A sentence. This is the most common form. The text is meant for a human reader.

{
  "detail": "Invalid API key"
}

An object that carries a code. Some refusals tied to your plan and some deletion confirmations return an object. The code field is stable. The message field changes from one version to the next.

{
  "detail": {
    "code": "QUOTA_EXCEEDED",
    "resource": "products",
    "current": 4820,
    "additional": 200,
    "max": 5000,
    "period": "monthly"
  }
}

A list. When validation of the body or of the parameters fails, detail is a list. Each entry describes a rejected value.

Depending on the rule that was not met, an entry can carry extra keys. Read loc and type. Never compare msg character by character.

#The headers that come with a response

#X-Request-Id, the identifier of every call

Every API response carries an X-Request-Id header. If your request sends one, yours is the one used. Otherwise we build one.

Record this value next to every call that fails. When you write to us about a refusal, give it to us: it takes us straight to the call concerned.

curl -sS -D - -o /dev/null \
  -X POST https://api.sealtrust.io/v1/partner/sellout \
  -H "Authorization: Bearer st_test_0000000000000000000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: exemple-sas-2026-08-20-0001" \
  -d '{"identifier": "DEM000000000", "retailer_code": "BTQ-EXEMPLE-01"}'

#The budget headers

A call authenticated by API key carries the rate counters in its response, including when the endpoint then refuses. A 400, a 403 due to your plan, to your quota or to a brand that does not match, therefore tell you how much rate budget you have left.

Three families of refusal carry no counter: the 401s, the 403s of a revoked or expired key, and the 403s of a scope missing from the key. Test for the presence of the header before reading its value.

A call that succeeds does not tell you how much daily quota you have left. The three X-Quota-* headers exist only on the 429 quota refusal. To follow this counter before hitting it, open the API key list in the console: for each key, it shows the day's consumption against its quota.

#The catalog, code by code

#400, your request is malformed

The server understood the request and refuses it. Fix the request. Replaying it as is will give the same result.

Row errors are returned to you all at the same time. You fix everything in one pass.

{
  "detail": {
    "error": "CSV invalide",
    "rows": [
      {
        "line": 2,
        "external_ref": "EX-0001",
        "error": "brand_id: Input should be a valid integer"
      }
    ]
  }
}

The line field is the line number in the file. The first data line carries number 2, since line 1 is the header.

In JSON, the shape changes: the position is called index and starts at 1, and external_ref is not carried over.

{
  "detail": {
    "error": "JSON invalide",
    "rows": [
      {
        "index": 1,
        "error": "metadata_uri: Field required"
      }
    ]
  }
}

#401, the API does not know who you are

Your request carries no valid identity. Fix the Authorization header. The first two rows of the table carry the WWW-Authenticate: Bearer header.

#403, the API knows who you are and refuses

Your identity is valid. Your key, your plan or your scope does not cover this operation. Replaying the request changes nothing.

The QUOTA_EXCEEDED object carries what you need to decide without writing to us:

{
  "detail": {
    "code": "QUOTA_EXCEEDED",
    "resource": "products",
    "current": 4820,
    "additional": 200,
    "max": 5000,
    "period": "monthly"
  }
}

#404, the resource does not exist for you

On the public endpoints and on the key-authenticated API, an object that exists outside your scope answers 404, exactly like a nonexistent object. A retailer of another brand, a subscription of another brand, a product of another brand: the answer is the same as for a made-up identifier.

The partner portal is the exception. When the product exists at a brand that has not accredited you, it answers 403 and says so, instead of 404.

#409, the current state forbids this operation

The request is correct. It conflicts with what already exists.

Both NFC seal messages start with a code in capitals followed by a colon. Test that prefix. The sentence that follows can be reworded.

#413, the upload is too large

#422, the API refuses a value you sent

This is the code for the parameters and the request bodies that the server can read and refuses. The detail field is then a list, unless the table says otherwise.

#429, you are calling too often

Four different counters return this code. The headers tell you which one refused.

A public ceiling refusal carries Retry-After, in seconds. The /timeline refusal is the exception and does not carry this header. Its window is fixed and lasts 60 seconds: wait that long before calling again.

The rate refusal of an API key names the ceiling that refused and its window:

{
  "detail": "Rate limit exceeded: 120 requests per 60 seconds"
}

When it is the ceiling of the brand that refuses, the sentence says so, it gives the ceiling of the brand, and it states that this key stays under its own ceiling. The X-RateLimit-Scope header is then brand.

Going past the daily quota takes another form:

{
  "detail": "Quota exceeded. Remaining today: 0/1000"
}

#500, the failure is on our side

There is nothing wrong with your request. Do not fix it. Note the X-Request-Id of the response, replay once after a few seconds, and report this identifier to us if the refusal persists.

The body of a 500 has no guaranteed shape. Write no logic against its content. Branch on the 500 status and on nothing else.

{
  "detail": "Internal Server Error"
}

On an operation that writes, such as minting a batch, treat the result as unknown. Replay with the same Idempotency-Key value as the first call: either the first call had gone through and you receive its response, or it had created nothing and the batch goes out.

#503, the API refuses the call without changing anything

#A 200 response can mean no

Six endpoints answer 200 in a case you must treat as a refusal. A client that only looks at the HTTP status misses all six of them. For each one, the field to read is named below.

The public check of a QR. GET /qr/verify answers 200 with "valid": false in five situations. The message field says which one applies. Always read valid.

{
  "valid": false,
  "message": "Invalid QR code signature. This QR code may be tampered with.",
  "uid_hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "token_id": null,
  "product_name": null,
  "brand_name": null,
  "image_url": null,
  "contract_address": null,
  "scan_area": null
}

The check of an originality signature. POST /originality/read-sig/verify answers 200 with "valid": false when the signature read on the chip does not verify against the public key used. The error field is then signature invalide. Read valid.

The integrity check of a passport. GET /passport/{identifier}/verify answers 200 even when a comparison fails. Three fields carry the result.

db_hash_match and ipfs_match are true, false or null. false means that the comparison failed. null means that it could not be made, which is different from a failure.

seal.chain_link_match is true or false, and it is absent from the seal block when the passport version was not sealed, or when it was sealed before the chaining existed. Read seal.sealed and seal.linked first: when both are true, seal.chain_link_match is present. It is the field that says whether a sealed version was modified after publication.

The check of the verifiable credential. GET /passport/{identifier}/vc/verify answers 200 with "verified": false when the signature of the credential does not verify against the key of the brand. The error field is then verification_failed and credential_subject is null. Read verified.

Batch tracking. GET /v1/partner/mint/batch/status/{job_id} answers 200 with "status": "unknown" when the batch cannot be found, and 200 with "status": "failed" when it failed. The values you will see are queued, started, finished, failed and unknown. Loop on status, and stop as soon as it leaves queued and started. Do not loop on is_finished: the unknown response carries only job_id and status, and a loop waiting for is_finished would never stop.

The sell-out declaration. POST /v1/partner/sellout answers 200 with "status": "already_activated" when this item had already been declared sold. Nothing was created a second time.

#What to replay, what not to replay

An automatic replay uses a delay that grows, and a bounded number of attempts. Replay on 503, on 500, and on the 429s that carry a Retry-After. On a 429 of daily quota, stop calling until the change of day. On the other 4xx codes, fix the request before any new call.

#Complete error handling, in three languages

These three programs do the same thing: they declare a sale, they tell the families of error apart, and they keep the request identifier.

Run these three programs on your server. The partner API does not accept a call coming from a browser, and an API key has no place in code sent to the browser. From a browser, reading X-Request-Id and reading Retry-After would return null: these two headers are not exposed to page code.

#!/usr/bin/env bash
set -u

entetes=$(mktemp)
trap 'rm -f "$entetes"' EXIT

reponse=$(curl -sS -w '\n%{http_code}' -D "$entetes" \
  -X POST https://api.sealtrust.io/v1/partner/sellout \
  -H "Authorization: Bearer st_test_0000000000000000000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"identifier": "DEM000000000", "retailer_code": "BTQ-EXEMPLE-01"}')

code=$(printf '%s' "$reponse" | tail -n 1)
corps=$(printf '%s' "$reponse" | sed '$d')
requete=$(grep -i '^x-request-id:' "$entetes" | tr -d '\r' | cut -d' ' -f2)

echo "code=$code request_id=$requete"
echo "$corps"

case "$code" in
  200) echo "vente enregistrée" ;;
  429|503) echo "réessayez plus tard" ;;
  5*) echo "panne serveur, signalez $requete" ;;
  *) echo "requête à corriger" ;;
esac

const reponse = await fetch("https://api.sealtrust.io/v1/partner/sellout", {
  method: "POST",
  headers: {
    Authorization:
      "Bearer st_test_0000000000000000000000000000000000000000000000",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    identifier: "DEM000000000",
    retailer_code: "BTQ-EXEMPLE-01",
  }),
});

const requestId = reponse.headers.get("X-Request-Id");
const corps = await reponse.json();

if (reponse.ok) {
  console.log("vente enregistrée", corps.status, requestId);
} else if (reponse.status === 429 || reponse.status === 503) {
  const attente = Number(reponse.headers.get("Retry-After") ?? 5);
  console.log("réessayez dans", attente, "secondes", requestId);
} else if (reponse.status >= 500) {
  console.log("panne serveur, signalez", requestId);
} else if (Array.isArray(corps.detail)) {
  for (const erreur of corps.detail) {
    console.log("champ refusé", erreur.loc.join("."), erreur.type);
  }
} else if (corps.detail && typeof corps.detail === "object") {
  console.log("refus code", corps.detail.code, requestId);
} else {
  console.log("refus", corps.detail, requestId);
}

import requests

reponse = requests.post(
    "https://api.sealtrust.io/v1/partner/sellout",
    headers={
        "Authorization": "Bearer st_test_0000000000000000000000000000000000000000000000",
        "Content-Type": "application/json",
    },
    json={"identifier": "DEM000000000", "retailer_code": "BTQ-EXEMPLE-01"},
    timeout=30,
)

request_id = reponse.headers.get("X-Request-Id")
corps = reponse.json()

if reponse.ok:
    print("vente enregistrée", corps["status"], request_id)
elif reponse.status_code in (429, 503):
    print("réessayez dans", reponse.headers.get("Retry-After", "5"), "secondes", request_id)
elif reponse.status_code >= 500:
    print("panne serveur, signalez", request_id)
else:
    detail = corps.get("detail")
    if isinstance(detail, list):
        for erreur in detail:
            print("champ refusé", ".".join(str(p) for p in erreur["loc"]), erreur["type"])
    elif isinstance(detail, dict):
        print("refus code", detail.get("code"), request_id)
    else:
        print("refus", detail, request_id)

#What to remember

• The error body always carries detail, in three forms: a sentence, an object with a code, or a list of rejected values.
• Branch your code on the HTTP status and on detail.code. Never compare the sentences.
• Keep the X-Request-Id of every failure. That is what we will ask you for.
• Replay on 503, on 500, and on the 429s that carry a Retry-After. Fix everything else.
• On a write, replay with the same Idempotency-Key value as the call whose outcome you do not know.
• Read valid, verified, status and the match fields: six endpoints describe a refusal inside a 200 response.