Error Handling

Understand API error responses, status codes, and error formats

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

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"
}

Code	Status	Description
authorization_header_missing	401	No Authorization or X-API-Key header provided
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

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

401 — Missing API Key

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.

403 — Insufficient Permissions

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.

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.

429 — Rate Limit Exceeded

You’ve exceeded the rate limit. Wait before retrying. 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.