Troubleshooting Guide
The troubleshooting guide provides technical assistance to Prescription Drug Plan (PDP) sponsors trying to use the AB2D API. For further assistance, visit Support.
HTTP response codes
- 200 HTTP response: request completed successfully
- 202 HTTP response: request accepted but still processing
- 400 HTTP response: bad request
-
General response when something is wrong (e.g., missing a request parameter or body).
- 401 HTTP response: unauthorized
-
Unauthorized, authentication has not been done or has not succeeded.
Returned for every authentication failure (missing token, invalid or expired token). Request a new bearer token and retry.
- 403 HTTP response: forbidden
-
Forbidden, authentication succeeded but the user doesn't have permissions to access the requested data.
Returned only when your token is valid but you are not allowed to make the request (for example, your organization is disabled, your contract is not attested, v3 is not enabled for your contract, or the job belongs to another organization). If this continues to happen, contact the AB2D team at ab2d@cms.hhs.gov.
- 404 HTTP response: page not found
-
Resource or page not found. You could authenticate but the API endpoint does not exist. Troubleshooting:
- Check the URL to make sure it exists. Enter it in a browser to check which error occurred. You won’t have passed credentials or necessary parameters, so it’ll give you another error. However, it shouldn’t give you a 404.
- If you’re using curl at the command line, you may have to escape characters. For example, $ is used in $Export and $Status, but $ is a variable value in the Bash command line.
- 405 HTTP response: method not allowed
-
You’re trying to execute a method which the endpoint does not support. For example, calling "/secure/get" as a POST method, even though the endpoint only supports GET methods.
- 429 HTTP response: too many requests
-
You’re creating too many job requests within a short period of time. Try waiting a bit before making another request.
- Unable to download bulk data file
-
- Your file name and/or job ID are incorrect. Check the job status again to verify these details.
- You requested to download the file more than 6 times.
- You waited too long to download your completed job files. Files expire and automatically delete after 72 hours.
- There’s a server error. If this continues to happen, contact the AB2D team at ab2d@cms.hhs.gov.
Learn more about standard HTTP Codes.
Common questions
Using the system that will access the API, open your browser and visit https://checkip.amazonaws.com. If you don’t have a browser query from your system’s command line:
- Linux/Mac: Open a terminal and run the command
curl -X GET checkip.amazonaws.com - Windows: Open a PowerShell terminal and run the command
Invoke-RestMethod -Method GET checkip.amazonaws.com
Check that you’re using the correct system. The IP address should match what you gave to the AB2D team during production access.
If the system is correct, check with your IT team to make sure you have a static IP address. If your IP address isn’t static, it may have changed. You must have a static IP address to use the API.
Use 1 of these methods:
- On the command line of the system you want to use, run 1 of the following commands:
-
Linux/Mac: In a terminal, run
curl -X GET https://api.ab2d.cms.gov/health --verbose -
Windows: In a PowerShell terminal, run
Invoke-RestMethod -Method GET https://api.ab2d.cms.gov/health - In Postman, create a new GET request against the URL https://api.ab2d.cms.gov/health. If the response has an HTTP status of 200 then your IP address can connect.
- Open a browser and visit https://api.ab2d.cms.gov/swagger-ui/index.html.
You can provide the AB2D team with up to 8 IP addresses.
Contact the AB2D team at ab2d@cms.hhs.gov to change your organization’s IP address(es).
You’re running too many jobs at once. If the API is busy, the job will be queued in a backlog.
- On the command line, run 1 of the following commands:
-
Linux/Mac: In a terminal, run
curl -X DELETE https://api.ab2d.cms.gov/api/v3/fhir/Job/{job_uuid}/$status --verbose. Make sure to fill in {job_uuid} with the ID of the running job. -
Windows: In a PowerShell terminal, run
Invoke-RestMethod -Method DELETE https://api.ab2d.cms.gov/api/v3/fhir/Job/{job_uuid}/$status. Make sure to fill in {job_uuid} with the ID of the running job. - In Postman, create a new DELETE request against the URL https://api.ab2d.cms.gov/api/v3/fhir/Job/{job_uuid}/$status. Note the request parameter {job_uuid} must be set in Postman.
- In a browser, visit https://api.ab2d.cms.gov/swagger-ui/index.html#/Status/deleteRequestUsingDELETE and enter your job ID.
The response will contain the list of files requested and the URLs to download them.
The status API will return an error for the job. Any files created will be deleted.
No, you can’t download files from a failed job. You must restart the job.
If you received a 403 error your bearer token may be expired or incorrect. Get another bearer token and restart the job.
4xx errors mean your files have been downloaded more than 6 times or are expired. Files expire and automatically delete after 72 hours.
AB2D sends data using Fast Healthcare Interoperability Resources (FHIR), a standard format for exchanging health data. AB2D v1 uses FHIR STU3. AB2D v2 and v3 use FHIR R4. All versions return one resource type: ExplanationOfBenefit (EOB).
We strongly recommend using AB2D v3. AB2D v1 and v2 will be retired on July 30, 2027, so PDPs should plan to migrate to v3 before then. Read the v3 migration guide here.
The data returned by each version is detailed in the AB2D Data Dictionary.
v3 offers the most filtering capability of all AB2D versions. v3 supports filtering on the date a claim was last updated using _since and _until parameters, as well as filtering on a claim's service-date using the _typeFilter parameter.
Unlike prior versions of the API, v3 does not automatically set these parameters for you. As a result, a request with no parameters will return all your data, which can cause long job run times or even timeouts and failed jobs.
v2 only supports the _since and _until parameters which are populated by default if a value is not provided. v1 only supports the _since parameter.
