Errors

Status codes

Code	Meaning	Typical cause
`200`	Success	Request completed
`201`	Created	Resource created
`204`	No Content	Resource deleted
`400`	Bad Request	Validation error in the body or parameters
`401`	Unauthorized	Missing or invalid `X-INVIEW-AUTH` header
`403`	Forbidden	Key is valid but not permitted — often an NPI outside your group
`404`	Not Found	Referenced pharmacy, listing or drug doesn’t exist
`409`	Conflict	The action conflicts with current state

Two error shapes

The API returns different bodies depending on where the request failed.

Validation errors — `400`

Model validation produces a field-keyed object:

{
  "errors": {
    "pharmacyNpi": ["Pharmacy NPI is required"],
    "searchingContext": ["The field SearchingContext is invalid."]
  },
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400
}

Each key is a request field; each value is a list of what’s wrong with it. This is the shape to surface to your users — it names exactly what to fix.

Everything else — `401`, `403`, `404`, `409`

{
  "error": "string",
  "statusCode": 403,
  "message": "string"
}

Because these two shapes differ, don’t parse errors by assuming message exists. Branch on the status code, or check for errors before reading it.

Common cases

409 when updating a listing

Marketplace listings, draft listings and cash offers can only be modified while Pending. Once purchased, accepted or cancelled, PUT and DELETE return 409. Re-read the object and check its status before offering an edit.

403 on a pharmacy you expected to have

The NPI isn’t in your group. Call GET /api/v1/pharmacies/search to see the current membership — a pharmacy added by NPI stays pending until it registers with InStockRx.

400 that's really a 401

Validation runs before authentication, so an unauthenticated and malformed request reports the malformed body. Fix the body; if you then get 401, it’s the key.

400 on quantity

quantity is conditional on fullPackage: exactly 1 when fullPackage is true, between 0.01 and the drug’s package size when it’s false.

Retries

v1 has no idempotency mechanism. Retrying a failed POST may create a second listing or offer.

Retry GET requests freely. For POST, PUT and DELETE, confirm the outcome with a search before retrying — a network timeout doesn’t tell you whether the write landed.

Idempotency keys arrive with v2.

Get started

Guides

Reference

Status codes

Two error shapes

Validation errors — `400`

Everything else — `401`, `403`, `404`, `409`

Common cases

Retries

​Status codes

​Two error shapes

​Validation errors — 400

​Everything else — 401, 403, 404, 409

​Common cases

​Retries

Status codes

Two error shapes

Validation errors — `400`

Everything else — `401`, `403`, `404`, `409`

Common cases

Retries