1. REST API for COVID-19 Data ClearinghouseREST APIs for COVID-19 Data Clearinghouse
  2. Status Codes

Status Codes

When you call any of the COVID-19 Data Clearinghouse REST operations, the response returns one of the standard HTTP status codes defined in the following table.:

HTTP Status Code Description
200 OK The request was completed successfully. A 200 status is returned for a successful GET or POST method.
201 Created The request was fulfilled and resulted in a new resource being created. The response includes a Location header which contains the canonical URI for the newly created resource.

A 201 status is returned from a synchronous resource creation or an asynchronous resource creation that completed before the response was returned.
202 Accepted The request was accepted for processing, but the processing has not been completed. The request may or may not eventually be acted upon, as it may be disallowed at the time processing actually takes place.

When specifying an asynchronous (__detached=true) resource creation (for example, when deploying an application), or update (for example, when redeploying an application), a 202 is returned if the operation is still in progress. If __detached=false, a 202 may be returned if the underlying operation does not complete in a reasonable amount of time.

The response contains a Location header of a job resource that the client should poll to determine when the job has finished. It also returns an entity that contains the current state of the job
400 Bad Request The request could not be processed because it contains missing or invalid information (such as a validation error on a parameter or a missing required value).
401 Unauthorized The request is not authorized. The authentication credentials included with this request are missing or invalid.
403 Forbidden The user cannot be authenticated. The user does not have authorization to perform this request.
404 Not Found The request includes a resource URI that does not exist.
405 Method Not Allowed The HTTP verb specified in the request (DELETE, GET, POST, PUT) is not supported for this request URI.
406 Not Acceptable The resource identified by this request is not capable of generating a representation corresponding to one of the media types in the Accept header of the request. For example, the request's Accept header is set to XML but the operation only returns JSON.
415 Unsupported Media Type The client's Content-Type header is not correct (for example, the client attempts to send the request in XML, but the resource can only accept JSON).
500 Internal Server Error The server encountered an unexpected condition that prevented it from fulfilling the request.
503 Service Unavailable The server is unable to handle the request due to temporary overloading or maintenance of the server. The COVID-19 Data Clearinghouse REST service is not currently running.

Table - COVID-19 Data Clearinghouse HTTP 500, 404, and 400 file errors

Number HTTP error code Type Message Explanation
3 404 Invalid secret Not found Either your secret is missing or incorrect. Check your records or contact your DCH administrator if you need assistance.
4 404 Wrong scope Not found Each API requires specific scopes (permissions). You may be missing one or more of the required permissions. Contact your DCH administrator for assistance.
5 404 Expired token Not found Your token expired. Generate a new token or get assistance from your DCH administrator.
6 404 Invalid or missing X509 cert in request Not found Your certificate expired. Ask your system administrator for assistance.
7 400 Wrong input format Invalid header row / Unable to find any valid records in the request The file header type may not match the payload type. If you are unsure of the payload type, try using the APIs for the other types. For example, if you used the CRVS API, try the batch and HL7 APIs.
8 404 Token missing in the request header Not found Retry the call after checking your token or generating a new token.
9 404 Invalid token or malformed token Not found Retry the call after checking your token or generating a new token. This message can be caused by a cut-and-paste error of the token string.
10 400 HL7 Translator fails Unable to translate HL7 records. The HL7 translation service is temporarily unavailable. Retry your quest after a short wait. If the unavailability continues, contact your DCH administrator.
14 500 Object store failure Put object <URL> failed . Either the bucket user in namespace already exists or you are not authorized to create it The underlying object storage service is not performing normally. Contact your DCH administrator for assistance.
15 500 Internal server error { "code": "InternalError", "message": "Internal error occurred" } An unspecified server error occured. Try uploading at a later time. Contact your DCH administrator if the problem persists.

Table - COVID-19 Data Clearinghouse validation and processing errors (HTTP 200)

Number Type Error column Error message Explanation
11 Processing error   Record Already Exists Cannot create a record that already exists. To change the record, use an update request.
12 Processing error   Record with site_key: <site key> doesn't exist for updating The record you are trying to update either does not exist or is not associated with your site_key.
13 Processing error   Record with site_key: <site key> doesn't exist for deleting The record you are trying to delete either does not exist or is not associated with your site_key.
16 Validation error vax_event_id / recip_id must be non-blank Either the vax_event_id or the the recip_id column or both do not contain a value for the record. Check the file for missing values and reupload your file.
17 Validation error ext_type must not be null The ext_type column cannot be null.
18 Validation error recip_last_name must not be null The recip_last_name column cannot be null.
19 Validation error recip_middle_name must not be null For CVRS records, the recip_middle_name column cannot be null. For HL7 records, providing a value is optional.
20 Validation error recip_first_name must not be null The recip_first_name column cannot be null.
21, 22, 23 Validation error recip_dob must be on or before admin_date recip_dob:
  • Cannot be null
  • Cannot be on or before the admin_date
  • Format must be YYYY-MM-DD
24 Validation error recip_sex must be one of [F, M, U] or must not be null Provide a valid value for the recip_sex column: F or M or U. The column cannot be null.
25 Validation error recip_address_street must not be null The recip_admin_street column cannot be null.
26 Validation error recip_address_street_2 must not be null For CVRS records, the recip_address_street_2 column cannot be null. For HL7 records, providing a value is optional.
27 Validation error recip_address_city must not be null The recip_address_city column cannot be null.
28 Validation error recip_address_county must be a FIPS 5-digit county code (can be null) Provide a valid FIPS five-digit county code for the recip_address_county column.
29 Validation error recip_address_state must be a two-character state abbreviation Provide a valid US two-character state abbreviation for the recip_address_state column.
30 Validation error recip_address_zip must be a valid ZIP. 5 digit or 5 digit + 4 are acceptable" (can be null) Provide a valid Zip Code for the recip_address_zip column in either the five-digit format or the five-plus-four-digit expanded format. The column can be null.
31, 32 Validation error recip_race_1 must be one of [1002-5, 2028-9, 2054-5, 2076-8, 2106-3, 2131-1, UNK, POL] Provide a valid value for the recip_race_1 column: 1002-5, 2028-9, 2054-5, 2076-8, 2106-3, 2131-1, UNK, POL. For CVRS records, the recip_race_1 column cannot be null. For HL7 records, providing a value is optional.
33 Validation error recip_race_2 must be one of [1002-5, 2028-9, 2054-5, 2076-8, 2106-3, 2131-1, UNK, POL] (can be null) Either leave the recip_race_2 column null or provide a valid value: 1002-5, 2028-9, 2054-5, 2076-8, 2106-3, 2131-1, UNK, POL
34 Validation error recip_race_3 must be one of [1002-5, 2028-9, 2054-5, 2076-8, 2106-3, 2131-1, UNK, POL] (can be null) Either leave the recip_race_2 column null or provide a valid value: 1002-5, 2028-9, 2054-5, 2076-8, 2106-3, 2131-1, UNK, POL
35 Validation error recip_race_4 must be one of [1002-5, 2028-9, 2054-5, 2076-8, 2106-3, 2131-1, UNK, POL] (can be null) Either leave the recip_race_2 column null or provide a valid value: 1002-5, 2028-9, 2054-5, 2076-8, 2106-3, 2131-1, UNK, POL
36 Validation error recip_race_4 must be one of [1002-5, 2028-9, 2054-5, 2076-8, 2106-3, 2131-1, UNK, POL] (can be null) Either leave the recip_race_2 column null or provide a valid value: 1002-5, 2028-9, 2054-5, 2076-8, 2106-3, 2131-1, UNK, POL
37 Validation error recip_race_5 must be one of [1002-5, 2028-9, 2054-5, 2076-8, 2106-3, 2131-1, UNK, POL] (can be null) Either leave the recip_race_2 column null or provide a valid value: 1002-5, 2028-9, 2054-5, 2076-8, 2106-3, 2131-1, UNK, POL
38, 39 Validation error recip_ethnicity must be one of [2135-2, 2186-5, UNK, POL] Provide a valid value for the recip_ethnicity column: 2135-2, 2186-5, UNK, POL. The column cannot be null.
40 Validation error admin_date invalid date format, expected: \"YYYY-MM-DD\" or \"YYYY-MM\ Change the date format of the admin_date column YYYY-MM-DD or YYYY-MM.
41 Validation error admin_date admin_date must be on or before submission date or admin_date should not be earlier than January 1, 2020 Change the the value of the admin_date column to a date on or before the submission date. Also, the admin_date cannot be earlier than January 1, 2020.
42, 43 Validation error cvx Must be an integer Provide an integer value for the cvx column. The column cannot be null.
44 Validation error vax_admin_site must be one of [LT, LA, LD, LG, LVL, LLFA, RT, RA, RD, RG, RVL, RLFA] Provide a valid value for the vax_route column: LT, LA, LD, LG, LVL, LLFA, RT, RA, RD, RG, RVL, RLFA.
45 Validation error vax_route must be one of [ID, IM, NS, IV, PO, OTH, SC, TD, C38238, C28161, C38284, C38276, C38288, C38676, C38299, C38305] Provide a valid value for the vax_route column: ID, IM, NS, IV, PO, OTH, SC, TD, C38238, C28161, C38284, C38276, C38288, C38676, C38299, C38305.
46, 47 Validation error dose_num Must be [1-10], \"INV\", or \"UNK\"" Provide a valid value for the dose_num column: [1-10] or \"INV\" or \"UNK\". The column cannot be null.
48, 49 Validation error vax_series_complete must be one of [YES, NO, UNK] Provide a valid value for the vax_series_complete column: YES, NO, or UNK (unknown). The column cannot be null.
50 Validation error responsible_org must not be null The responsible_org column cannot be null.
51 Validation error admin_name must not be null The admin_name column cannot be null.
52 Validation error admin_type must not be null The admin_type column cannot be null.
53 Validation error admin_address_county must be a FIPS 5-digit county code Provide a valid FIPS five-digit county code for the admin_address_county column.
54 Validation error admin_address_state must be a two-character state abbreviation Provide a valid US two-character state abbreviation for the admin_address_state column.
55 Validation error admin_address_zip must be a valid ZIP. 5 digit or 5 digit + 4 are acceptable Provide a valid Zip Code for the admin_address_zip column in either the five-digit format or the five-plus-four-digit expanded format.
56, 57 Validation error vax_refusal message must be one of [YES, NO] Provide a valid value for the vax_refusal column: YES or NO. The column cannot be null.
58, 60 Validation error cmorbid_status must be one of [YES, NO, UNK] Provide a valid value for the cmorbid_status column: YES, NO, or UNK (unknown). The column cannot be null.
59, 61 Validation error serology message must be one of [YES, NO, UNK] Provide a valid value for the serology column: YES, NO, or UNK (unknown). The column cannot be null.
62 DB status failure   DB INSERT ERROR This error is rare. DCH was not able to add the record to the database for an unspecified reason. Check the failed record for errors. If there are multiple unexpected errors, there may be a system issue. Try uploading at a later time. Contact your DCH administrator if the problem persists.
63 Validation error vax_expiration should not be on December 1, 2020 or earlier Either omit records with invalid early dates or correct the invalid early dates.
64 Validation error vax_expiration invalid date format, expected: \"YYYY-MM-DD\" or \"YYYY-MM\ Change the date format of the record column with an invalid date format to YYYY-MM-DD or YYYY-MM.