Search Plus UI Blocks

Find a block, a category or a site

API errors referenceapi-errors-reference

Use in Plus UI
npx shadcn@latest add https://blocks.plusui.com/r/api-errors-reference.json

Reference · 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"
  }
}