Skip to main content

​
Error Handling

All RxScale APIs return consistent error responses. This page documents the error formats, HTTP status codes, and common error scenarios.

​
HTTP Status Codes

Status CodeMeaningWhen It Occurs
200OKSuccessful GET, PATCH, or POST request
201CreatedResource successfully created
204No ContentResource successfully deleted
400Bad RequestValidation error, missing parameters, or invalid request body
401UnauthorizedMissing or invalid authentication (token or API key)
403ForbiddenValid authentication but insufficient permissions
404Not FoundResource does not exist or you lack access to it
409ConflictResource already exists (duplicate)
422Unprocessable EntityRequest is well-formed but contains invalid data (e.g., corrupt PDF)
429Too Many RequestsRate 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.

​
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" — Unexpected server-side error (details logged internally)
  • "Missing required parameters: from and to" — Specific missing parameter info

​
Authentication Error

Authentication and authorization failures return a code and description: 
{
  "code": "authorization_header_missing",
  "description": "Authorization header is expected"
}
CodeStatusDescription
authorization_header_missing401No Authorization or X-API-Key header provided
invalid_header401Malformed authorization header or unparseable token
token_expired401JWT token has expired
invalid_claims401Token audience or issuer mismatch
invalid_api_key401API key not found or inactive
api_key_missing401X-API-Key header is expected
permission_denied403API key lacks required permission for this endpoint

​
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.

​
Common Error Scenarios

Request:
curl https://api.rxscale.com/v1/management/products
Response:
{
  "code": "api_key_missing",
  "description": "X-API-Key header is expected"
}
Fix: Include the X-API-Key header in your request.
Request: Trying to write with a read-only API key.
{
  "code": "permission_denied",
  "description": "API key lacks required permission: orders_write"
}
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.
{
  "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.
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.
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.
You’ve exceeded the rate limit. Wait before retrying. 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.