> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rxscale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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                                                  |

<Warning>
  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.
</Warning>

## Error Response Formats

RxScale APIs use three error response formats depending on the error type.

### Standard Error

Most errors return a simple error string:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="401 — Missing API Key">
    **Request:**

    ```bash theme={null}
    curl https://api.rxscale.com/v1/management/products
    ```

    **Response:**

    ```json theme={null}
    {
      "code": "api_key_missing",
      "description": "X-API-Key header is expected"
    }
    ```

    **Fix:** Include the `X-API-Key` header in your request.
  </Accordion>

  <Accordion title="403 — Insufficient Permissions">
    **Request:** Trying to write with a read-only API key.

    ```json theme={null}
    {
      "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.
  </Accordion>

  <Accordion title="404 — Resource Not Found">
    **Request:** Accessing a resource with an invalid UID or without access.

    ```json theme={null}
    {
      "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.
  </Accordion>

  <Accordion title="400 — Validation Error">
    **Request:** Submitting an invalid request body.

    ```json theme={null}
    {
      "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.
  </Accordion>

  <Accordion title="409 — Duplicate Resource">
    **Request:** Creating a resource that already exists.

    ```json theme={null}
    {
      "error": "Pharmacy SKU already exists"
    }
    ```

    **Fix:** The resource already exists. Use a GET request to retrieve it, or use PATCH to update it.
  </Accordion>

  <Accordion title="429 — Rate Limit Exceeded">
    You've exceeded the rate limit. Wait before retrying. See [Rate Limits](/rate-limits) for details and best practices.
  </Accordion>
</AccordionGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Implement exponential backoff for 429">
    When rate limited, wait and retry with increasing delays. Never retry immediately in a tight loop.
  </Accordion>

  <Accordion title="Log the full error response">
    For debugging, log the entire response body including status code and headers. RxScale support may ask for these details.
  </Accordion>
</AccordionGroup>