Skip to main content

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

For security reasons, unauthorized access returns 404 instead of 403 on resource endpoints. This prevents attackers from discovering which resources exist. If you receive a 404, verify both that the resource UID is correct and that your API key has the required permissions.

Error Response Formats

RxScale APIs use three error response formats depending on the error type.
Some responses are not JSON at all: a rate-limited 429, and the 404 or 405 returned for a path or HTTP method an API does not have, come back as Content-Type: text/html with a short HTML error page. Always branch on the HTTP status code before parsing the body — a client that calls response.json() unconditionally fails on exactly the response its retry logic was written for. See Rate Limits.

Standard Error

Most errors return a simple error string:
Common messages:
  • "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
In the Public API every error additionally carries a 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:
Each key is the field name, and the value is an array of error messages for that field. Fix all listed fields and retry. For a field inside a list or an object, 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 stable code 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": "..."}}.
Send an external_reservation_id with every reservation. A request you repeat because you did not receive the answer is then answered with the draft order that already exists. One case remains: after an internal_error the outcome is not known. In rare cases the draft order was created before the failure without RxScale recording it, and a retry then reserves the stock a second time. That first reservation is released on its own after 24 hours. The same can happen, more rarely still, after a shopify_error.

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 unsupported carrier. pharmacy identifies the pharmacy the request was for.
  • {"error": "<message>"} — you sent tracking links for an order that is already completed.

Common Error Scenarios

Request:
Response:
Fix: Include the X-API-Key header in your request.
Request: Trying to write with a read-only API key.Management API and Public API — use code to detect this error; description is human-readable text:
External Pharmacy API:
Fix: Check your API key’s permissions. You may need to create a new key with the required permissions.
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.
Request: Submitting an invalid request body.
Fix: Check each field listed in the error and provide valid values.
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.
Request: A body above the 32 MiB cap.
Fix: Split the payload across several requests.
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

The status code tells you the error category. Parse the response body for details only after checking the status.
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.
When rate limited, wait and retry with increasing delays. Never retry immediately in a tight loop.
For debugging, log the entire response body including status code and headers. RxScale support may ask for these details.