API errors referenceapi-errors-reference
Use in Plus UI
npx shadcn@latest add https://blocks.plusui.com/r/api-errors-reference.jsonReference · 5 variants
← → to step through · + on a thumbnail to compare side by side (up to 3)
/preview/api-errors-reference
Open ↗Default content
{
"eyebrow": "Getting started",
"title": "Errors",
"lead": "Stampcove uses ordinary HTTP status codes and always returns a JSON `error` object you can branch on. Branch on `type`, never on `message` — messages are written for people and may change.",
"statuses": [
{
"code": 200,
"name": "OK",
"meaning": "The request worked. Creating a label returns `201 Created`."
},
{
"code": 400,
"name": "Bad request",
"meaning": "A parameter is missing or malformed. `param` names it."
},
{
"code": 401,
"name": "Unauthorized",
"meaning": "No API key, or a revoked one."
},
{
"code": 402,
"name": "Payment required",
"meaning": "Your balance can't cover the postage for this label."
},
{
"code": 404,
"name": "Not found",
"meaning": "No label, rate or tracking number with that ID in this mode."
},
{
"code": 409,
"name": "Conflict",
"meaning": "The label can't change state, e.g. voiding one that has shipped."
},
{
"code": 422,
"name": "Unprocessable",
"meaning": "The request is valid JSON but the carrier refused it."
},
{
"code": 429,
"name": "Too many requests",
"meaning": "Slow down. `Retry-After` says for how long."
},
{
"code": 500,
"name": "Server error",
"meaning": "Something broke on our side. Safe to retry with the same idempotency key."
}
],
"errorObject": {
"title": "The error object",
"fields": [
{
"name": "type",
"type": "string",
"description": "A stable, machine-readable code. Branch on this."
},
{
"name": "message",
"type": "string",
"description": "A sentence for people. Show it in logs, not to customers."
},
{
"name": "param",
"type": "string | null",
"description": "The request parameter at fault, when there is one."
},
{
"name": "carrier_code",
"type": "string | null",
"description": "The carrier's own code when a carrier refused the request."
},
{
"name": "request_id",
"type": "string",
"description": "Quote it to support; it finds the request in our logs."
}
],
"example": "{\n \"error\": {\n \"type\": \"address_invalid\",\n \"message\": \"The recipient postcode does not match the town.\",\n \"param\": \"to.postcode\",\n \"carrier_code\": null,\n \"request_id\": \"req_8Lq2VhX0\"\n }\n}"
},
"errors": [
{
"type": "parameter_missing",
"status": 400,
"meaning": "A required parameter is not in the request.",
"fix": "Add the parameter named in `param`."
},
{
"type": "address_invalid",
"status": 400,
"meaning": "An address failed validation for its country.",
"fix": "Check `param`; call `POST /v1/addresses/verify` first."
},
{
"type": "parcel_too_heavy",
"status": 422,
"meaning": "No service on this route takes a parcel this heavy.",
"fix": "Split the shipment or request a freight rate."
},
{
"type": "rate_expired",
"status": 409,
"meaning": "The rate you bought was quoted more than 24 hours ago.",
"fix": "Get a fresh rate and create the label with its `rate_id`."
},
{
"type": "insufficient_balance",
"status": 402,
"meaning": "Your balance is lower than the label's price.",
"fix": "Top up in the dashboard or turn on auto top-up."
},
{
"type": "label_already_shipped",
"status": 409,
"meaning": "The carrier has scanned the parcel, so it can't be voided.",
"fix": "Start a return instead."
},
{
"type": "carrier_unavailable",
"status": 503,
"meaning": "The carrier's API is down or timing out.",
"fix": "Retry with backoff, or quote another carrier."
},
{
"type": "rate_limited",
"status": 429,
"meaning": "More than 100 requests a second from this key.",
"fix": "Wait for `Retry-After` seconds and retry."
}
],
"labels": {
"statuses": "HTTP status codes",
"errors": "Error types",
"status": "Status",
"name": "Name",
"meaning": "Meaning",
"type": "Type",
"fix": "What to do",
"field": "Field",
"example": "Example",
"copy": "Copy",
"copied": "Copied"
}
}