Skip to main content

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS
A lock ( ) or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

Trouble­shooting 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: forbidden

Your token is incorrect or has expired. Authentication has not been completed successfully.

403 HTTP response: unauthorized

You don’t have permission to access the requested data. This can happen for a variety of reasons:

  • Your token has expired.
  • You have specified a contract that is not yours.
  • You’re not authorized to use the API.
  • Authentication has failed.
403 HTTP response: forbidden

Authentication succeeded, but you don’t have permission to access the requested data. This can happen due to a variety of reasons:

  • The credentials provided may have a typo or syntax error (e.g., spaces, hidden characters).
  • The credentials provided may have been encoded to Base64 incorrectly.
  • You’re connected to the sandbox idP (test.idp.idm.cms.gov) instead of the production idP (idp.cms.gov).
  • Authentication may have failed because of an incorrect header. "Authorization : Basic Auth" is the correct header.
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 http://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:

  1. 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
  2. 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.
  3. 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/v2/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/v2/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/v2/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.

STU3 and R4 are different Fast Healthcare Interoperability Resources (FHIR) versions for data transmission. AB2D provides STU3 and R4 versions for 1 resource type, ExplanationOfBenefit.

Version 1 of the API uses STU3 (https://api.ab2d.cms.gov/api/v1/fhir) and version 2, which is recommended by the AB2D team, uses R4 (https://api.ab2d.cms.gov/api/v2/fhir).

Requests made to both versions of the API are largely the same except for the way they process parameters. The data returned by each version is detailed in the AB2D Data Dictionary. Learn how to migrate from V1 to V2.

The default value for the _since parameter changes between versions. The _until parameter is also only available with V2.

In V1, a date must be specified to use _since. If no _since value is specified, it will default to January 1, 2020 or your organization's attestation date, whichever is later. In V2, if no _since value is specified, it will default to the date of your last successful export. If this is your first job, it will default to the same date as V1. Learn how to use parameters.

cms.gov

official website of the U.S. Department of Health and Human Services and the Centers for Medicare & Medicaid Services.

Looking for U.S. government information and services?
Visit USA.gov