DICOMweb errorswhy a call fails or comes back empty

DICOMweb errors are HTTP errors, so the status code tells most of the story. This page ties each code, each Warning header and the empty-list case to the rule in PS3.18 behind it, and shows how the server picks a media type from your Accept header.

Filter the tables

48 rows

Start from the status code

What each common code means for the transaction you called, and the first thing to check.

Code	Transaction	What it means	First check
`400`	Any	Bad syntax, or a supported query parameter with an invalid value, or a bad header.	Query string syntax, percent-encoding, a `window` parameter missing a part, `quality` outside 1 to 100.
`401` / `403`	Any	No valid credentials, or not allowed. A server can answer 404 instead, so as not to reveal that the resource exists.	The token or login, and the rights for that study. Do not read a 404 as proof that the study is absent.
`404`	Retrieve	The target resource does not exist, or the server does not say that it does.	The UIDs in the URL, the base path, and whether the instance was moved.
`405`	Any	The method is not supported by that resource. The response lists the allowed methods in an `Allow` header.	Using `POST` on a search or `GET` on a store.
`406`	Retrieve, Search	None of the media types you accepted can be supplied.	The `Accept` header, the `type=` and `transfer-syntax=` parameters, and single part media types on a multi-item resource.
`409`	Store	Nothing was stored because of a conflict: an unsupported SOP Class or a Study Instance UID that does not match the URL.	The SOP Classes the server supports, and whether you posted to `/studies/{study}` with another study in the body.
`202`	Store	Some instances were stored, others have warnings or failures.	The response body and the `Warning` header for the failing instances.
`410`	Retrieve	The resource was deleted.	A cached link to a study that was removed.
`413`	Retrieve, Search	The resource is too large to return, or the search was too broad.	Add match keys, use `limit` and `offset`, or request frames instead of the whole instance.
`415`	Store	The server does not accept the `Content-Type` of the request.	The `Content-Type` of your body: use `multipart/related; type="application/dicom"` or metadata plus bulk data parts.
`501`	Various	Used for a SOP Class that is not supported.	The SOP Classes in the conformance statement.
`503`	Any	Temporary overload or maintenance.	Retry later.

A search returned nothing, or too little

An empty result is not an error. Work through these in order.

Symptom	Likely cause	Rule behind it
`200` with `[]` for a study that exists	A key does not match: a wrong date or range, a name without a wild card, a modality in the wrong attribute.	Search uses the C-FIND matching rules. Names are literal unless fuzzy matching is supported.
Fewer studies than expected	The server paged the result: it returned the system limit, or your `limit`.	The response has `Warning: 299 ... There are <n> additional results that can be requested`. Ask again with `offset`.
Different pages overlap or skip a study	Studies were added or removed between the page requests.	The same request gives the same order only while the matches do not change.
`fuzzymatching=true` has no effect	The server does not support fuzzy matching.	It searches literally and adds `Warning: 299 ... The fuzzymatching parameter is not supported`.
A filter on an attribute is ignored	The server does not support that parameter or attribute. Unsupported parameters are ignored.	The server processes the request as if the parameter was not there, and may add a warning.
Series or instance attributes missing from a study search	Attributes of a lower level in `includefield` are not returned at study level.	Series or Instance level attributes in `includefield` are not returned for studies.
A series search returns the study attributes too	You searched All Series or All Instances.	For those resources the response also includes the study level, and for All Instances the series level, attributes.
Old systems return 204 for no match	The server follows an earlier release of the standard.	The current text specifies 200 with an empty payload. A client should accept both.

How the server chooses the media type

The Selected Media Type is picked per part and per resource category. Knowing the order explains most 406 answers.

Step	What the server does
1	Identify the resource category of the target: single frame image, multi-frame image, video, text, or other.
2	Take the highest priority media type that it supports, for that category, from the Accept query parameter (WADO-URI `contentType`).
3	If none is supported, take the highest priority supported media type from the Accept header.
4	If the Accept header has a wildcard range that matches the category, use the default media type of the category.
5	Otherwise answer 406 Not Acceptable.

Priority comes from q values (1 when absent), taken from the most specific matching media range. Two cases that surprise: asking for a rendered study with only single part media types in the Accept header gives 406, even for a study with one frame; and 406 is also the answer when the pixels would be too long for the Explicit VR Little Endian transfer syntax.

Media type and transfer syntax mistakes

Common mistakes when a retrieve or store fails or returns an unexpected format.

Mistake	What happens	Rule
Several `transfer-syntax` values in one media type	An invalid header.	A media type may have only one transfer-syntax parameter with one value. Offer a choice as several media types with q values.
Asking for Implicit VR Little Endian	It is not available.	Implicit VR Little Endian and Explicit VR Big Endian must not be used with web services.
No `transfer-syntax` parameter	You get the default.	Explicit VR Little Endian for the instance categories, unless the server has only lossy pixels or pixels too long for it.
`transfer-syntax=*`	The server returns what it stores.	The wildcard lets the server skip transcoding.
Single part `application/dicom` for a series	The server ignores it, and returns 406 if nothing else remains.	Single part media types are only for a resource that is one item.
Quotes around `type=` in `multipart/related`	Some servers reject quotes, others reject their absence.	The standard allows both, and notes that servers differ. A client can try the other form on failure.
`transfer-syntax` or `charset` in a WADO-URI request	`400`	They are forbidden in URI Service requests. WADO-URI uses a query parameter instead.
Posting a PNG or GIF as pixel data	The server transforms it into an uncompressed or lossless form, and drops transparency or an alpha channel.	PNG and GIF are transformed. JPEG, JPEG 2000, JPEG XL and MPEG are kept unchanged, without further lossy compression.

Reading a multipart response

Retrieve and store payloads of several items are `multipart/related`.

Part header	Meaning	Tip
`Content-Type` of the message	`multipart/related; type="..."; boundary=...`. The `type` is the media type of the root part.	Read the boundary from this header, not by guessing.
`Content-Type` of a part	The single part media type of that item, with its transfer syntax parameter.	Each part is chosen separately, so parts can differ.
`Content-Location` of a part	Identifies the resource in that part: a frame, an instance, a bulk data URI.	This is how you match frames to numbers and bulk data to the metadata.
Order of parts	Metadata parts that reference bulk data come before the bulk data part. The root is the first part unless `start` says otherwise.	Do not assume bulk data comes first.

Warning headers

A 200 can still carry a warning. The standard uses the HTTP `Warning` header with code 299.

Warning text	When
`299 <service>: There are <n> additional results that can be requested`	A search had more matches than were returned.
`299 <service>: The fuzzymatching parameter is not supported. Only literal matching has been performed.`	You asked for fuzzy matching and the server cannot do it.
`299 <service>: The emptyvaluematching parameter is not supported. Empty Value Matching has not been performed.`	You asked for empty value matching and the server cannot do it.
`299 <service>: The following annotation values are not supported: <values>`	You asked for annotations the renderer does not support.
`A700 <service>: Out of memory` (example)	A store response may carry a DICOM status code and a reason in the Warning text.

A checklist before you blame the server

Check the request, then the conformance statement.

Check	Why
The base URI and the resource path	A web server may host several services under different base paths.
UIDs in the URL are not padded and have no whitespace	Query parameter values must not be padded to an even length.
Special characters are percent-encoded	`#`, `[`, `]`, `&`, `=` and `,` must be encoded in a query value, and non-ASCII characters too.
The Retrieve Capabilities response (`OPTIONS /`)	It describes the resources, media types and optional parameters that the server supports.
The conformance statement	It lists the resources, media types, optional parameters, maximum number of matches, and whether the server is native or a proxy.
A proxy in front of a DIMSE server	A proxy has fewer mandatory search resources, and behavior may follow the DIMSE side.

Glossary

Status Report: A payload that explains a failure or warning. A failure response should have one.
Warning header: An HTTP header that the server uses to flag something on an otherwise successful response, with code 299 for DICOMweb warnings.
Accept header: The request header that lists the media types the client accepts, with q values for preference.
Selected media type: The media type the server chose for the response, from the ones the client accepts.
Transfer syntax parameter: A media type parameter that names the DICOM transfer syntax of the pixel encoding that is wanted.
Boundary: The string that separates the parts of a multipart payload, declared in the Content-Type header.

Summary

Read the status code first: 400 the request, 406 the media type you can get, 415 the media type you sent, 409 a conflict on store, 404/410 the resource.
A search with no match is 200 with an empty list. Look at keys, paging and the Warning header.
Warning: 299 can come with a 200: more results, fuzzy matching not supported, empty value matching not supported.
The server chooses the media type per category from the Accept query parameter, then the Accept header, then a default.
Offer transfer syntax choices as several media types with q values, never several values in one.
A 404 can hide a permission problem. Policy may require it.

Common questions

Why do I get 406 Not Acceptable from WADO-RS?

None of the media types in your Accept header, or Accept query parameter, can be supplied for that resource category. Common causes are a single part media type for a resource with several items, a transfer syntax the server cannot produce, or pixel data too long for the default Explicit VR Little Endian encoding. Try a wildcard or the default media type for the category.

What is the difference between 406 and 415?

406 is about the response: the server cannot give you a representation that you accept. 415 is about the request: the server does not support the Content-Type you sent, which typically happens when storing.

Why does STOW-RS return 202?

The server stored some of the instances, but there are warnings or failures for others. The body says which. A 409 means that nothing could be stored for a conflict, such as an unsupported SOP Class or a Study Instance UID that differs from the URL.

My QIDO-RS search returns an empty array. Is something wrong?

Not necessarily. No matches is a normal 200 with an empty payload. Check the matching keys: dates and ranges, names with a wild card, and the level of the attribute you searched on. Also check the Warning header and the paging parameters.

Does a 404 mean the study does not exist?

Not always. A server is allowed to answer 404 instead of 401 or 403 so that it does not reveal that a resource exists. A deleted resource should be reported as 410, not 404, when the server knows it was deleted.

Try it yourself

← All lessons