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

Status Code	Meaning	When It Occurs
`200`	OK	Successful GET, PATCH, or POST request
`201`	Created	Resource successfully created
`204`	No Content	Resource successfully deleted
`400`	Bad Request	Validation error, missing parameters, or invalid request body
`401`	Unauthorized	Missing or invalid authentication (token or API key)
`403`	Forbidden	Valid authentication but insufficient permissions
`404`	Not Found	Resource does not exist or you lack access to it
`409`	Conflict	Resource already exists (duplicate)
`413`	Content Too Large	Request body is above the 32 MiB cap
`422`	Unprocessable Entity	Request is well-formed but contains invalid data (e.g., corrupt PDF)
`429`	Too Many Requests	Rate limit exceeded

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:

{
  "error": "Resource not found"
}

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

Authentication Error

Authentication failures, and permission failures in the Management API and the Public API, return a code and description:

{
  "code": "authorization_header_missing",
  "description": "Authorization header is expected"
}

Code	Status	Description
`authorization_header_missing`	401	No `Authorization` header provided (token authentication)
`invalid_header`	401	Malformed authorization header or unparseable token
`token_expired`	401	JWT token has expired
`invalid_claims`	401	Token audience or issuer mismatch
`invalid_api_key`	401	API key not found or inactive
`api_key_missing`	401	`X-API-Key` header is expected
`permission_denied`	403	API key lacks required permission for this endpoint (Management API and Public API)

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.

Validation Error

Schema validation failures return field-level error details:

{
  "error": {
    "shop_uid": ["Missing data for required field."],
    "quantity": ["Not a valid integer."]
  }
}

Each key is the field name, and the value is an array of error messages for that field. Fix all listed fields and retry.

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.

Status	Body	When It Occurs
`400`	`{"error": {"<field>": ["<message>"]}}`	A field in the request body, or a query parameter value such as an unknown `status`, failed validation. `"Unknown field."` means the request body contains a field the endpoint does not accept. Query parameters the endpoint does not know are ignored.
`400`	`{"error": "Bad request"}`	Generic error — see below.
`401`	`{"code": "...", "description": "..."}`	The `X-API-Key` header is missing (`api_key_missing`) or the key is not valid (`invalid_api_key`).
`403`	`{"error": "Permission denied"}`	The API key lacks the permission the endpoint requires.
`404`	`{"error": "Resource not found"}`	The resource does not exist, or it exists but belongs to another pharmacy or pharmacy group.
`413`	`{"error": "Request body too large"}`	The request body is above 32 MiB.
`429`	HTML page, no `Retry-After` header	Rate limit exceeded. See Rate Limits.
`404`, `405`	HTML page	The path does not exist, or the endpoint does not support the HTTP method.

{"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:

requests RxScale refuses, for example changing the status of a cancelled order;
on endpoints that take a request body (except complete_order), a body that is not valid JSON or is sent without Content-Type: application/json;
a group-wide API key without a pharmacy_uid, or with a pharmacy_uid outside its pharmacy group.

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 has three more 400 variants:

{"error": ["Invalid JSON in request body"]} — the request body is not valid JSON. Here error is a list.
{"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

401 — Missing API Key

Request:

curl https://api.rxscale.com/v1/management/products

Response:

{
  "code": "api_key_missing",
  "description": "API key header is expected"
}

Fix: Include the X-API-Key header in your request.

403 — Insufficient Permissions

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:

{
  "code": "permission_denied",
  "description": "API key lacks required permission: <permission>"
}

External Pharmacy API:

{
  "error": "Permission denied"
}

Fix: Check your API key’s permissions. You may need to create a new key with the required permissions.

404 — Resource Not Found

Request: Accessing a resource with an invalid UID or without access.

{
  "error": "Resource not found"
}

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

Request: Submitting an invalid request body.

{
  "error": {
    "patient_data": {
      "first_name": ["Missing data for required field."],
      "date_of_birth": ["Not a valid integer."]
    }
  }
}

Fix: Check each field listed in the error and provide valid values.

409 — Duplicate Resource

Request: Creating a resource that already exists.

{
  "error": "Pharmacy SKU 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

Request: A body above the 32 MiB cap.

{
  "error": "Request body too large"
}

Fix: Split the payload across several requests.

429 — Rate Limit Exceeded

You’ve exceeded the rate limit. The response body is HTML, not JSON:

Content-Type: text/html; charset=utf-8

<!doctype html>
<html lang=en>
<title>429 Too Many Requests</title>
<h1>Too Many Requests</h1>

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

The status code tells you the error category. Parse the response body for details only after checking the status.

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

When rate limited, wait and retry with increasing delays. Never retry immediately in a tight loop.

Log the full error response

For debugging, log the entire response body including status code and headers. RxScale support may ask for these details.

Getting Started

External Pharmacy API

Management API

Scheduling API

Public API

Patient API

Anamnesis API

Webhooks

Guides

Error Handling

Error Handling

HTTP Status Codes

Error Response Formats

Standard Error

Authentication Error

Validation Error

External Pharmacy API Error Responses

Common Error Scenarios

Best Practices

​Error Handling

​HTTP Status Codes

​Error Response Formats

​Standard Error

​Authentication Error

​Validation Error

​External Pharmacy API Error Responses

​Common Error Scenarios

​Best Practices

Error Handling

HTTP Status Codes

Error Response Formats

Standard Error

Authentication Error

Validation Error

External Pharmacy API Error Responses

Common Error Scenarios

Best Practices