Error Handling
RxScale APIs share most of their error formats. This page documents the error formats, HTTP status codes, and common error scenarios, and says where an API differs.HTTP Status Codes
Error Response Formats
RxScale APIs use three error response formats depending on the error type.Standard Error
Most errors return a simple error string:"Resource not found"— Resource doesn’t exist or you lack access"Bad request"— Generic error; the reason is recorded only in RxScale’s logs, not in the response. In the External Pharmacy API it also covers requests RxScale refuses, such as changing the status of a cancelled order — see External Pharmacy API Error Responses"Missing required parameters: from and to"— Specific missing parameter info
code — see Public API Reason Codes.
Authentication Error
Authentication failures, and permission failures in the Management API and the Public API, return a code and description:
The External Pharmacy API does not use
permission_denied: a key without the required permission gets 403 with {"error": "Permission denied"}. See External Pharmacy API Error Responses.
The Public API returns the same text under error as well, so that one key holds the message for every error:
Validation Error
Schema validation failures return field-level error details:error is nested the same way the request body is. The Public API adds code and a flat details map, so you do not have to walk the nesting: each key is the dotted path of one refused field.
lines.0.quantity is the quantity of the first line; list positions start at 0. A message about the request body as a whole sits under _schema.
Public API Reason Codes
Every error the Public API returns as JSON carries a stablecode next to error.
Branch on code, not on the HTTP status or on the text of error: one status covers
several reasons, and the wording of error can change.
Two of these codes use
403. That status is also used when your API key lacks a permission; that response carries code: "permission_denied". Branch on code.
The prescription checkout additionally uses duplicate_prescription_injection and
order_already_exists (both 409); they are described with that endpoint. One response
predates the codes and has none: an invalid or unsigned prescription PDF answers 422
with {"errors": {"message": "..."}}.
Lines
unknown_sku, insufficient_stock and product_unavailable_in_shop name the lines at
fault in a lines array, with the identifiers you sent and the quantity you asked
for. A line that is fine never appears in it.
external_id is your own product identifier for that SKU, or null when the SKU is not
mapped for your provider. On the weed.de endpoint it is the externalId weed.de sent. sku_uid is null when an external_id could not be resolved
to a SKU at all. For product_unavailable_in_shop, lines is absent when the refusal
cannot be attributed to a specific line — treat a missing lines key as “one of these
products”, not as “no problem”.
With unknown_sku, a cart of one valid and one unknown line is refused as a whole, and
lines holds the unknown line only:
insufficient_stock is raised on the reservation endpoint before any draft order is
created, so a refused reservation leaves nothing behind. RxScale returns this code
only when the Shopify variant tracks inventory and its inventoryPolicy is DENY —
the shop does not allow selling more than is in stock. When inventoryPolicy is
CONTINUE, overselling is allowed: the draft order is created and the endpoint
returns 200, even if the requested quantity is above the stock on hand. A variant
that does not track inventory is treated the same way. Shopify still reports
inventoryPolicy DENY for those variants, and they have no stock figure; RxScale
does not refuse them.
quantity is what you requested and available_stock what the shop can currently cover,
so available_stock is always lower. Lines that are covered, lines whose variant
allows overselling (inventoryPolicy CONTINUE), and lines whose variant does not
track inventory, do not appear. The same
available_stock field name is used by
POST /v2/{service}/products/{shop_identifier}/live-stock, which reports the quantity
on hand without attempting a reservation. That live-stock response does not apply the
inventoryPolicy rule above.
New
code values may be added over time. Treat an unrecognised code as a generic
failure rather than rejecting the response.External Pharmacy API Error Responses
The External Pharmacy API returns the error responses below. Rely on the HTTP status code, and treat the body as additional information.{"error": "Bad request"} is a generic error. The reason is recorded only in RxScale’s logs, not in the response. Besides unexpected errors, it covers a page or limit value that is not a whole number on the order and payout lists.
Do not retry these requests automatically. Contact RxScale support with the endpoint, HTTP method, timestamp, and request body (without secrets such as your API key).
PATCH /pharmacy_orders/{uid}/complete_order reads its body without a Content-Type header, so it never returns the Content-Type message above. It has two more 400 variants:
{"error": {...}, "pharmacy": {"uid": "...", "display_name": "..."}}— the request body failed validation, for example because of an unsupportedcarrier.pharmacyidentifies the pharmacy the request was for.{"error": "<message>"}— you sent tracking links for an order that is already completed.
Common Error Scenarios
401 — Missing API Key
401 — Missing API Key
Request:Response:Fix: Include the
X-API-Key header in your request.403 — Insufficient Permissions
403 — Insufficient Permissions
Request: Trying to write with a read-only API key.Management API and Public API — use External Pharmacy API:Fix: Check your API key’s permissions. You may need to create a new key with the required permissions.
code to detect this error; description is human-readable text:404 — Resource Not Found
404 — Resource Not Found
Request: Accessing a resource with an invalid UID or without access.Fix: Verify the resource UID is correct. If you’re sure the UID is valid, check that your API key has permission to access the resource.
400 — Validation Error
400 — Validation Error
Request: Submitting an invalid request body.Fix: Check each field listed in the error and provide valid values.
409 — Duplicate Resource
409 — Duplicate Resource
Request: Creating a resource that already exists.Fix: The resource already exists. Use a GET request to retrieve it, or use PATCH to update it.
413 — Request Body Too Large
413 — Request Body Too Large
Request: A body above the 32 MiB cap.Fix: Split the payload across several requests.
429 — Rate Limit Exceeded
429 — Rate Limit Exceeded
You’ve exceeded the rate limit. The response body is HTML, not JSON:No
Retry-After or X-RateLimit-* headers are sent. Fix: Wait at least one second
— a full rate-limit window — then retry. See Rate Limits for details
and best practices.Best Practices
Always check the HTTP status code first
Always check the HTTP status code first
The status code tells you the error category. Parse the response body for details only after checking the status.
Handle 404 defensively
Handle 404 defensively
A
404 can mean the resource doesn’t exist OR you lack access. Don’t assume which — verify your API key permissions alongside the resource UID.Implement exponential backoff for 429
Implement exponential backoff for 429
When rate limited, wait and retry with increasing delays. Never retry immediately in a tight loop.
Log the full error response
Log the full error response
For debugging, log the entire response body including status code and headers. RxScale support may ask for these details.