API errors

Ez a tartalom még nem érhető el a jelenlegi nyelven.

Every error response of the Globe API has the same JSON body with a stable error code. This page lists each code with its HTTP status, its cause, whether a retry helps, and the extra fields it carries.

Error body

{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key is missing the `labels:print` scope.",
    "details": {
      "retry": "no",
      "next_action": "none",
      "required_scope": "labels:print"
    },
    "request_id": "req_k3J9xQ2mT7vA",
    "doc_url": "https://docs.globe.appfleece.com/reference/api-errors#insufficient_scope"
  }
}

Field	Description
`code`	Stable, machine-readable code. Branch on it. New codes are an API change
`message`	Text for people. The wording can change at any time
`details`	Fields specific to the code, listed below. Missing when there is nothing to add
`request_id`	ID of this request (`req_…`). The same value is in the `X-Request-Id` header
`doc_url`	Link to the code’s section on this page

internal_error never carries details and its message never contains the underlying exception.

`retry` and `next_action`

Errors that can end a label creation carry details.retry and details.next_action. A few endpoints set a different value than the default listed for a code; the value in the response wins.

`retry`	`next_action`	What to do
`no`	`none`	Sending the same request again will not succeed
`after_fix`	`fix_and_retry`	Fix the cause (the order, the store’s settings or the request), then send it again
`later`	`retry_later`	Nothing to fix. Send it again after `Retry-After`
`manual`	`manual_check`	A person has to check the shipment at the carrier and decide

Request ID and support

Every response, successful or not, carries X-Request-Id. When you contact support about a failed call, send the request_id. It is the only way to find the request in Globe’s logs, because request bodies and query strings are never logged.

Errors from `POST /labels`

An error from POST /labels means this call created no shipment.
If the call got as far as creating a label creation record, the error names it in details.label_creation_id. That creation is failed and its Idempotency-Key is released, so the same key starts a new attempt. idempotency_conflict, and label_exists for a key bound to an abandoned creation, name that earlier creation instead.
GET /label-creations/{id} answers 200 for a failed creation. The code is in error.code, and next_action says what to do.
Some codes come from the carrier step, after the API already answered 202. You see them on the next poll, on a repeat of the request with the same key, or as errorCode in the label_creation.updated webhook.

The origin never answers 502 or 504. If you get one, or no response at all, the outcome of a POST /labels is unknown: send the same request again with the same Idempotency-Key. It joins or replays the first attempt and never books a second shipment.

401 Unauthorized

`unauthorized`

The request has no bearer credential: no Authorization header, a different scheme, or Bearer with no key. The message tells a missing header apart from a header that is not a bearer credential.

Send Authorization: Bearer glb_live_…. The word Bearer and a space come before the key. Pasting the bare key into a header field is the most common setup mistake.

`invalid_token`

The key is unknown, malformed, revoked or expired. The API does not say which.

Check that the key is copied in full. A rotated key stops working when its overlap ends. Create a new key in Settings → API if needed.

403 Forbidden

`access_required`

API access is not enabled for the store, or the Globe app is not installed on it. The API is in beta and support enables it per store.

Ask in the support chat in the Globe admin.

Detail	Description
`how_to_enable`	How to request access. Not present when the app is not installed
`support_email`	Support contact

`api_paused`

Globe support paused API access for the store. Every key of the store is refused, and no key is revoked. The store has no switch for it.

Ask in the support chat in the Globe admin to resume access.

Detail	Description
`how_to_enable`	How to ask for access to resume
`support_email`	Support contact

`plan_required`

The store has no active Globe subscription and no free access.

Start or restore a subscription in Globe.

`write_access_required`

details.retry: no · next_action: none

The endpoint writes, and the store’s write access is off. This covers POST /labels (dry runs included), POST /labels/{id}/printed and resolve. Reads keep working.

Ask support to enable label creation for the store.

`insufficient_scope`

details.retry: no · next_action: none

The key does not carry the scope the endpoint requires. include: ["document"] on POST /labels also needs labels:print.

Create a key with the permission that includes the scope. See Permissions and scopes.

Detail	Description
`required_scope`	The missing scope

404 Not Found

`not_found`

The endpoint does not exist, or the label, label creation, carrier account or order does not exist in this store. An ID that belongs to another store or is malformed gets the same answer. GET /orders/{order_id}/label-document also answers not_found when the order has no current outbound label. GET /label-documents answers it when any one of the IDs is unknown.

Check the ID and the path. IDs keep their prefix (lbl_…, lcr_…, ca_…).

Detail	Description
`order_id`	Only for an order without a current outbound label

405 Method Not Allowed

`method_not_allowed`

The path exists but does not accept this HTTP method. The Allow header lists the methods it accepts.

Detail	Description
`allowed_methods`	Methods the path accepts

409 Conflict

`idempotency_conflict`

details.retry: no · next_action: none. With state: in_flight: later · retry_later

The Idempotency-Key is already bound to a different request. On POST /labels the key binds to its label creation for 30 days, and the body is compared after normalization.

Use a new key for a new operation. Send the identical body to get the original answer back.

On POST /labels/{id}/printed, state: in_flight means the first request with this key is still running. The response carries Retry-After: 2. Send the same request again after it to get the first answer.

Detail	Description
`idempotency_key`	The key you sent
`label_creation_id`	`POST /labels`: the creation the key belongs to
`state`	`in_flight` when the first request is still running

`duplicate_request`

The request used Idempotency-Key: auto and an identical request ran less than 60 seconds ago, so it was not repeated. Only POST /labels/{id}/printed accepts auto.

Wait for Retry-After, or change the request if you mean a separate action.

Detail	Description
`ran_seconds_ago`	When the identical request ran
`retry_after_seconds`	Seconds until the same request is accepted again

`label_pending`

The label is not finished yet, so it has no document. PPL labels wait for the carrier’s shipment number. Labels created through the API wait for their creation to finish.

Retry after Retry-After: 2 seconds for labels created through the API, 30 seconds otherwise. Do not create the label again.

Detail	Description
`label_id`	The label
`label_creation_id`	The creation, for labels created through the API

`document_pending`

The label is ready but its PDF is not stored yet. This happens right after a label is created through the API, and for Packeta shipments through an external carrier until the carrier assigns its own number. The carrier is not called.

Retry after Retry-After: 2 seconds during the first 10 minutes after the label was created, 60 seconds after that. Do not create the label again.

Detail	Description
`label_id`	The label
`label_creation_id`	The creation, when it is still running

`render_in_progress`

Globe renders this document at the carrier on demand. Either a render of the same label and format is already running (Retry-After: 2), or the store already has 3 renders running (Retry-After: 5).

Retry after Retry-After.

Detail	Description
`label_id`	The label, when the same label is being rendered
`concurrency_limit`	The store’s render limit, when that limit was reached

`ambiguous_current_set`

GET /orders/{order_id}/label-document found two current outbound labels that cover the same fulfillment order. Globe does not guess which one to print.

Let a person choose the labels, then download them with GET /label-documents?label_ids=….

Detail	Description
`order_id`	The order
`current_label_ids`	The order’s current outbound labels
`conflicting_fulfillment_orders`	Fulfillment orders claimed by more than one of them (`order` for whole-order labels)

`label_exists`

details.retry: no · next_action: none

Existing labels or an earlier creation block the target of POST /labels, and the request’s on_existing mode does not allow the result. details.reason says why. To replace the labels, send on_existing: "create_new" with replaces listing what blocks the target (the IDs below). A replaced label stays a valid, paid shipment at the carrier. See Existing labels.

`reason`	Cause
`existing_label_ready`	`on_existing: "reject"` and ready labels cover the target
`order_has_label`	`PUT /orders/{order_id}/pickup-point`: the order already has labels (`label_ids`). A label is made for one pickup point
`existing_label_differs`	`on_existing: "return"`, and the request names a carrier account, service, COD, declared value or weight that differs from the existing label. Amounts are compared after the carrier’s rounding
`existing_label_unverifiable`	`on_existing: "return"` with one of those values, but the existing label does not record it, or more than one label covers the target
`existing_label_pending`	A covering label is still pending at the carrier. `reject` and `create_new` get this while it is pending for less than 10 minutes. With `return` such a label is adopted instead; this reason then means it did not become ready within 5 minutes. A label pending for more than 10 minutes alerts support
`partial_coverage`	Existing labels cover only part of the target
`ambiguous_current_set`	Two current labels of the order cover the same fulfillment order
`existing_label_expired`	A covering label is older than 60 days. Its document is gone, but it still blocks
`existing_label_on_replaced_fulfillment_order`	A label sits on a fulfillment order that an order edit replaced. Resolve it in the Globe admin
`existing_label_coverage_unknown`	An older label does not record which fulfillment orders it covers, so it cannot be ruled out
`shipment_outside_globe`	An earlier creation for this target is `abandoned`: the shipment exists and is handled outside Globe. Also the answer when the `Idempotency-Key` belongs to that creation

Detail	Description
`reason`	One of the reasons above
`existing_label_ids`	The blocking labels
`differences`	`existing_label_differs`: `{field, requested, existing}` per differing value
`uncovered_fulfillment_order_ids`	`partial_coverage`: fulfillment orders without a label
`label_creation_ids`	`shipment_outside_globe`: the abandoned creations
`label_creation_id`	The abandoned creation when the key belongs to it, otherwise this request’s creation

`unresolved_creation`

details.retry: manual · next_action: manual_check

An earlier label creation for the same fulfillment order is in needs_attention. Globe does not know whether that shipment exists at the carrier. This blocks every on_existing mode, create_new included.

Check the shipment at the carrier and resolve the earlier creation with POST /label-creations/{id}/resolve. Unresolved, it becomes abandoned 24 hours after it entered needs_attention; a new label then needs on_existing: "create_new" with that creation’s ID in replaces. See needs_attention and resolve.

Detail	Description
`label_creation_id`	The first unresolved creation
`label_creation_ids`	Every unresolved creation that covers the target

`creation_in_progress`

details.retry: later · next_action: retry_later

Another label creation, or a label export from the Globe admin or Flow, holds the fulfillment order right now. Only on_existing: "reject" and "create_new" get this error. With "return" the creation waits for the holder instead. PUT /orders/{order_id}/pickup-point gets it while a label creation for the order is running (details.label_creation_id); change the point once it has finished.

Retry after Retry-After (5 seconds).

Detail	Description
`held_by`	`creation` (another API creation), `export` (admin or Flow) or `unknown`
`label_creation_id`	The holding creation, when it is one

`precondition_failed`

details.retry: after_fix · next_action: fix_and_retry

on_existing: "create_new" was sent with a replaces list that does not match exactly what blocks the target today. The list can miss a blocking label, name a label that does not block, or miss an abandoned creation.

Send replaces equal to details.current_blocking. If the set changed since you last read it, check the labels before you replace them.

Detail	Description
`current_blocking`	The label (`lbl_…`) or creation (`lcr_…`) IDs that block the target now

`already_resolved`

details.retry: no · next_action: none

The label creation was already resolved with a different outcome, possibly by a concurrent request. Repeating the same outcome answers 200.

Detail	Description
`label_creation_id`	The creation
`outcome`	The outcome it was resolved with

`not_resolvable`

details.retry: no · next_action: none

The creation is not in needs_attention, or the request asked for not_created while attention.shipment_at_carrier is exists. The carrier has that shipment: find it by attention.carrier_reference, print the label from the carrier’s portal and resolve with shipment_exists.

Detail	Description
`label_creation_id`	The creation
`status`	The creation’s status, when it is not `needs_attention`

`resolve_too_early`

details.retry: later · next_action: retry_later

outcome: "not_created" was sent less than 15 minutes after the creation reached the carrier. The carrier may still be processing the shipment.

Retry after Retry-After, or at resolve_allowed_at.

Detail	Description
`label_creation_id`	The creation
`resolve_allowed_at`	The earliest time `not_created` is accepted

410 Gone

`document_expired`

The label is older than 60 days, so its document is never served again and the label cannot be marked printed. Its metadata stays readable through GET /labels.

If the parcel still has to ship, create a new label with on_existing: "create_new" and the old label in replaces.

Detail	Description
`label_id`	The label

`label_not_reissuable`

The label’s document cannot be issued again: no copy is stored, and the carrier cannot render it again without a side effect, or refused to. DPD HU, DPD EasyShip and Pošta bez hranic labels without a stored copy get this answer.

A retry does not help. Print the label in the Globe admin.

Detail	Description
`label_id`	The label

422 Unprocessable Entity

`validation_error`

details.retry: after_fix · next_action: fix_and_retry

A parameter, header or body is invalid. Examples: an unknown field (the POST /labels body is a closed schema), a wrong type, an amount in the wrong format or over the limit, a missing or too short Idempotency-Key (or auto on POST /labels), create_new without replaces, include together with dry_run, or a body over 256 KB.

The status is 400 instead of 422 when the API key is in the query string (?api_key=). Keys are only accepted in the Authorization header.

Fix the field named in details and send the request again.

Detail	Description
`parameter`	The invalid field or query parameter
`header`	The invalid header, e.g. `Idempotency-Key`
`received`	What was sent (shortened)
`allowed`	Accepted values
`max`	Upper limit, where one applies (for `cod.amount` and `declared_value.amount`: `"9999999.99"`)
`max_bytes`	Body size limit, for a body that is too large

`unsupported_version`

The Globe-Version header names a version that is not live.

Send one of allowed_versions, or leave the header out to use the version pinned on the key.

Detail	Description
`requested_version`	The version you sent
`allowed_versions`	The live versions

`format_not_supported`

The document cannot be produced in the requested format. zpl is reserved for a later version. Some carriers offer only one of label and a4.

Use a format from details.supported, or from the label’s document.formats.

Detail	Description
`label_id`	The label, when the carrier is the limit
`requested_format`	The format you asked for
`supported`	Formats that work for this label

`document_unavailable`

The label has no document Globe can serve.

`reason`	Cause
`no_label`	The record is a Packeta claim or a DPD pickup, not a shipment label
`label_failed`	The label failed at the carrier
`carrier_excluded`	Magyar Posta, DPD SK, DPD LV, DPD LT, DPD EE or UPS. The API never produces these documents; for Magyar Posta, printing closes the shipment manifest at the carrier. Print them in the Globe admin
`not_isolated`	An older DPD HU label whose stored file may contain other labels of the same batch

Detail	Description
`label_id`	The label
`reason`	One of the reasons above

`carrier_rejected`

details.retry: after_fix · next_action: fix_and_retry

The carrier refused the shipment. This comes from the carrier step, so you usually see it on the label creation, not on the first response. The carrier’s own text is never returned, because carriers echo addresses in it.

PPL can also refuse a shipment at import, after it accepted the batch. The label then becomes failed with failure_reason: carrier_import_rejected, and the creation fails with this code and reason: other, also from needs_attention.

Fix the cause on the order or the carrier account, then send POST /labels again. The same key starts a new attempt. The same shipment refused 3 times within 60 minutes is blocked as repeated_rejection.

`reason`	Cause
`address_invalid`	The carrier did not accept the address
`postcode_invalid`	The carrier did not accept the postcode
`service_not_available`	The service is not available for this shipment
`weight_out_of_range`	The weight is outside the service’s range
`cod_limit`	The COD amount is over the carrier’s limit
`pickup_point_invalid`	The carrier did not accept the pickup point
`credentials_invalid`	The carrier refused the account’s login
`account_not_permitted`	The carrier account is not allowed to use this service
`other`	A recognized refusal without a more specific reason

Detail	Description
`reason`	One of the reasons above
`label_creation_id`	The creation

`repeated_rejection`

details.retry: after_fix · next_action: fix_and_retry

The carrier refused this exact shipment 3 times within 60 minutes, or refused shipments for this fulfillment order 30 times within 24 hours. Globe did not call the carrier this time. A change to what goes to the carrier (address, pickup point, service, weight, COD, declared value, options) or to the carrier account counts as a new shipment and starts from zero. Creating the label in the Globe admin stays possible.

Detail	Description
`scope`	`fingerprint` (the same shipment) or `fulfillment_order_daily` (the daily cap)
`blocked_until`	When the block ends
`carrier_rejected`	The reason of the last refusal
`label_creation_id`	The creation

`label_validation_failed`

details.retry: after_fix · next_action: fix_and_retry. With cod_dropped_by_carrier_module: no · none

The shipment failed the checks Globe runs before it calls the carrier. Nothing was sent. The checks run when the request arrives and again in the worker right before the carrier call. A refusal in the worker ends the creation failed with this code, never needs_attention.

Fix the order or the carrier account settings. Each entry of details.issues is {code, field?, raw?}.

Issue	Cause
`pickup_point_required`	The service needs a pickup point and the order has none
`pickup_point_malformed`	The order’s pickup point does not belong to the carrier’s network or cannot be read
`cod_not_supported`	The service cannot collect cash on delivery. Send `cod.amount` `"0"` to ship without it
`cod_metafield_invalid`	An order metafield that decides COD holds an invalid value. `field` names it: `globe/cod_value`, `globe/currency`, or `custom.converted_value` (Packeta) when it is zero or not a number
`cod_dropped_by_carrier_module`	The carrier would receive a COD above zero as zero, for example after its rounding or a converted amount. The parcel would ship without collecting it
`packeta_foreign_pickup_point`	Packeta: the pickup point belongs to a different network than the service
`pickup_point_id_missing`	Packeta: the pickup point ID is missing
`cod_packet_currency_mismatch`	Packeta: the COD would go out in a currency other than the packet currency, usually because only some of the `custom.converted_*` and `custom.packet_value` metafields are set. `details.cod_currency` and `details.packet_currency` show both
`cod_bank_account_missing`	PPL: the carrier account has no IBAN for paying out the COD
`cod_variable_symbol_missing`	PPL: the order name has no digits, and PPL needs them as the COD variable symbol
`missing_phone`	MyGLS with a pickup point needs the recipient’s phone number. For other carriers a missing phone is only a warning
`psd_requires_gls_point`	MyGLS: the PSD service needs a GLS pickup point
`account_config_incomplete`	The carrier account settings are incomplete. Checks without their own issue code also report this, with the internal code in `raw`
`email_invalid`	DPD CZ: the recipient’s email is invalid
`cod_foreign_pickup_point`	DPD CZ: COD to a pickup point of another network

`currency_mismatch`

details.retry: after_fix · next_action: fix_and_retry

The currency of cod or declared_value is not the currency the carrier receives for this shipment. Globe never converts amounts. The carrier’s currency is the label currency (the globe/currency metafield, otherwise the order currency). For Packeta it can be custom.converted_currency when the order has the converted metafields.

Send the amount in expected_currency.

Detail	Description
`field`	`cod` or `declared_value`
`expected_currency`	The currency the carrier receives

`order_not_eligible`

details.retry: after_fix · next_action: fix_and_retry

The order cannot get a label as requested.

`reason`	Cause
`order_not_found`	No order matches. The Shopify search index can lag a new order by a few seconds when you send `order_name`; retry or use `order_id`
`order_cancelled`	The order is cancelled. Also reported when it was cancelled after the request and before the carrier call
`nothing_to_ship`	The order has nothing left to ship, or the labels in `replaces` cover no fulfillment order
`fulfillment_orders_not_ready`	No fulfillment order can ship yet; they are scheduled or on hold
`fulfillment_order_not_in_order`	The named fulfillment order belongs to another order
`fulfillment_order_not_open`	The named fulfillment order is not open for shipping, or it closed before the carrier call
`fulfillment_order_not_parcel`	The named fulfillment order is the in-store pickup, local delivery or retail part of a split order, or has no delivery method. It never travels as a carrier parcel. Name the shipping fulfillment order, or leave `fulfillment_order_ids` out. Also returned without `fulfillment_order_ids` when the order’s parcel already has a label and only its pickup, local delivery or retail part is left (`existing_label_ids` lists the labels). To re-ship the parcel, send `on_existing: "create_new"` with `replaces`
`too_many_fulfillment_orders`	The order has more than 20 fulfillment orders. Use the Globe admin
`order_fulfilled`	`PUT /orders/{order_id}/pickup-point`: the order is fulfilled; its pickup point can no longer change
`no_pickup_point_method`	`PUT /orders/{order_id}/pickup-point`: the order’s shipping method is not a pickup point method of any of your carriers

Detail	Description
`reason`	One of the reasons above
`order_id`	The order
`fulfillment_order_id`	The fulfillment order the reason is about
`delivery_method`	`fulfillment_order_not_parcel`: its delivery method type
`status`	`fulfillment_order_not_open`: its status
`existing_label_ids`	Labels of the order, where relevant
`fulfillment_orders`	`fulfillment_orders_not_ready`: the waiting fulfillment orders

`order_ambiguous`

details.retry: after_fix · next_action: fix_and_retry

order_name matches more than one order.

Send order_id instead.

Detail	Description
`order_name`	The name you sent

`pickup_point_not_available`

details.retry: after_fix · next_action: fix_and_retry

PUT /orders/{order_id}/pickup-point cannot set this point on the order. Find a valid one with GET /orders/{order_id}/pickup-points.

`reason`	Cause
`carrier_not_offered`	The order’s shipping method does not map to this carrier. `details.carriers` lists the carriers it maps to
`not_found`	No active point with this ID in the order’s shipping country
`not_found_nearby`	The carrier’s points are read live from the carrier, and this one is not among the 50 nearest to the order’s shipping address
`type_not_allowed`	The order’s shipping method does not offer this type of point, for example a branch on a box-only rate
`requires_customer_id`	The point needs a customer ID the customer types in at selection (DHL Packstation, PPL ParcelBox in Germany)

`fulfillment_order_required`

details.retry: after_fix · next_action: fix_and_retry

The order has fulfillment orders to ship at more than one location, and the request named none.

Name one in fulfillment_order_ids, or send all_locations: true to ship all of them on one label.

Detail	Description
`fulfillment_orders`	`{id, status, assigned_location_name, existing_label_ids}` per fulfillment order

`carrier_selection_failed`

details.retry: after_fix · next_action: fix_and_retry

Globe could not choose a carrier account and service for the order.

`reason`	Cause
`no_carrier_accounts`	The store has no carrier accounts
`no_matching_rule`	No account’s rules match the order. Send `carrier_account_id` and `service_code`
`ambiguous_accounts`	More than one account matches. Send `carrier_account_id`
`service_unresolved`	The account has no service for this order, or `service_code` is not in its catalogue. Send a `service_code` from `GET /carrier-accounts`
`carrier_account_not_found`	The account does not exist or belongs to another store. Also reported when the account was deleted before the carrier call
`service_not_creatable`	The service is a return product. The API creates outbound labels only
`carrier_not_enabled`	Label creation through the API is switched off for the account (`api_creation: "not_enabled"`)

Detail	Description
`reason`	One of the reasons above
`carrier_account_id`	The account the reason is about
`service_code`	The service the reason is about
`candidates`	`ambiguous_accounts`: `{carrier_account_id, carrier}` per matching account

`unsupported_parameter`

details.retry: after_fix · next_action: fix_and_retry

The request sends a parameter the carrier account does not take:

carrier_options contains a key the account does not declare. Use only the keys in the account’s options from GET /carrier-accounts.
declared_value is sent to a carrier whose services have declared_value.supported: false in GET /carrier-accounts. Send the request without declared_value. See Declared value.

Detail	Description
`parameter`	`carrier_options.<key>` or `declared_value`
`carrier_account_id`	`declared_value`: the carrier account

429 Too Many Requests

`rate_limited`

details.retry: later · next_action: retry_later

A rate limit is exhausted. Nothing was created and no Idempotency-Key was bound. The response carries Retry-After and the X-RateLimit-* headers of the refusing bucket.

Wait for Retry-After. The limits are listed under Rate limits.

Detail	Description
`bucket`	The exhausted bucket
`scope`	`key` or `shop`
`limit`	The bucket’s limit
`window_seconds`	The bucket’s window. `null` for `write_queue_depth`
`retry_after_seconds`	Same as `Retry-After`

`bucket`	Limit
`read_key_per_second`, `read_key_per_minute`	Reads per key
`document_key_per_minute`, `document_shop_per_minute`	Stored documents per key and per store
`render_shop_per_minute`	Documents rendered at the carrier per store
`dry_run_key_per_second`, `dry_run_key_per_minute`, `dry_run_shop_per_minute`	Dry runs
`write_key_per_second`, `write_shop_per_minute`	`POST /labels` requests
`write_shop_per_day`	Label creations per store and day
`create_new_daily`	`on_existing: "create_new"` creations per store and day
`write_queue_depth`	Creations waiting in the store’s queue. `Retry-After` is the time the queue needs to drain (5 to 120 seconds)
`resolve_key_per_second`, `resolve_shop_per_hour`	Resolve requests
`print_key_per_second`, `print_shop_per_minute`	`POST /labels/{id}/printed`

shopify_budget and render_concurrency are reserved bucket names.

500 Internal Server Error

`internal_error`

Something failed on Globe’s side. The response has no details.

Send the request_id to support. For POST /labels, a 500 usually means the call failed before a creation record existed. Send the same request again with the same Idempotency-Key: if a creation does exist, the repeat joins it instead of creating a second one.

503 Service Unavailable

`carrier_unavailable`

details.retry: later · next_action: retry_later

The carrier, or a service Globe needs for the operation, is not available right now. Document responses carry Retry-After (5 seconds).

`reason`	Where	Cause
`timeout`	Documents	The carrier did not render the document in time
`carrier_error`	Documents	The carrier refused the render
`render_error`	Documents	The render failed on Globe’s side
`storage_error`	Documents	The stored copy could not be read, and the carrier cannot render it again
`circuit_open`	Label creation	The carrier account had several unclear results in a row. New creations for it fail for 5 minutes without calling the carrier
`account_rejecting`	Label creation	The carrier refused the account 5 times within 10 minutes (invalid credentials or a missing permission). `retry` is `after_fix`: fix the account. Creating labels in the Globe admin stays possible

Rendered documents also get this code, without a reason, when Globe cannot count renders. Globe then refuses the render instead of running it unmetered.

Detail	Description
`reason`	One of the reasons above
`label_id`	Documents: the label
`retry_after_seconds`	`circuit_open`: seconds until the account is tried again
`label_creation_id`	Label creation: the creation

`shopify_unavailable`

details.retry: later · next_action: retry_later

Globe could not read the order from Shopify: Shopify throttled or refused the read, or the store has no usable Shopify session. Nothing was created.

Retry after Retry-After (5 seconds). If it keeps failing, contact support with the request_id.

Detail	Description
`what`	Which read failed
`throttled`	`true` when Shopify throttled the read

`temporarily_unavailable`

details.retry: later · next_action: retry_later

Globe cannot accept writes right now. Either the counters behind the write limits are unavailable (Retry-After: 5), or the label creation queue of the whole platform is full (Retry-After: 30). Nothing was created.

Retry after Retry-After.

`not_started`

details.retry: later · next_action: retry_later

The label creation did not reach the carrier within 5 minutes after it was created, so Globe never sent it. Nothing exists at the carrier. The creation is failed and its Idempotency-Key is released.

Send POST /labels again. The same key starts a new attempt.

Stored on a label creation

`resolved_not_created`

This code is never an HTTP response. It is the error.code of a creation that a person resolved with outcome: "not_created". Its retry is later, so next_action is retry_later: send POST /labels again to create the label, with the same key or a new one.

API errors

Error body

retry and next_action

Request ID and support

Errors from POST /labels

401 Unauthorized

unauthorized

invalid_token

403 Forbidden

access_required

api_paused

plan_required

write_access_required

insufficient_scope

404 Not Found

not_found

405 Method Not Allowed

method_not_allowed

409 Conflict

idempotency_conflict

duplicate_request

label_pending

document_pending

render_in_progress

ambiguous_current_set

label_exists

unresolved_creation

creation_in_progress

precondition_failed

already_resolved

not_resolvable

resolve_too_early

410 Gone

document_expired

label_not_reissuable

422 Unprocessable Entity

validation_error

unsupported_version

format_not_supported

document_unavailable

carrier_rejected

repeated_rejection

label_validation_failed

currency_mismatch

order_not_eligible

order_ambiguous

pickup_point_not_available

fulfillment_order_required

carrier_selection_failed

unsupported_parameter

429 Too Many Requests

rate_limited

500 Internal Server Error

internal_error

503 Service Unavailable

carrier_unavailable

shopify_unavailable

temporarily_unavailable

not_started

Stored on a label creation

resolved_not_created

`retry` and `next_action`

Errors from `POST /labels`

`unauthorized`

`invalid_token`

`access_required`

`api_paused`

`plan_required`

`write_access_required`

`insufficient_scope`

`not_found`

`method_not_allowed`

`idempotency_conflict`

`duplicate_request`

`label_pending`

`document_pending`

`render_in_progress`

`ambiguous_current_set`

`label_exists`

`unresolved_creation`

`creation_in_progress`

`precondition_failed`

`already_resolved`

`not_resolvable`

`resolve_too_early`

`document_expired`

`label_not_reissuable`

`validation_error`

`unsupported_version`

`format_not_supported`

`document_unavailable`

`carrier_rejected`

`repeated_rejection`

`label_validation_failed`

`currency_mismatch`

`order_not_eligible`

`order_ambiguous`

`pickup_point_not_available`

`fulfillment_order_required`

`carrier_selection_failed`

`unsupported_parameter`

`rate_limited`

`internal_error`

`carrier_unavailable`

`shopify_unavailable`

`temporarily_unavailable`

`not_started`

`resolved_not_created`