This document serves as a supplementary to Blue Button 2.0 API Developer Documents. It gives more details on the most common error responses and how to properly handle them.
| Status Code | End Point URL | Error Message | Action | Comments |
|---|---|---|---|---|
| 400 BAD REQUEST |
/v[12]/o/.* | the response comes from blue button. Example message: error: unsupported grant type |
Fix the request |
request has invalid parameter(s) |
| 403 FORBIDDEN |
/v[12]/o/authorize/ /v[12]/o/authorize/(?P[\w-]+)/$ /v[12]/o/token |
You do not have permission to perform this action. | request does not pass permission check | |
| 403 FORBIDDEN |
/v[12]/o/authorize/ /v[12]/o/authorize/(?P[\w-]+)/$ |
This application, {your app name}, is temporarily inactive. If you are the app maintainer, please contact the Blue Button 2.0 API team. If you are a Medicare Beneficiary and need assistance, please contact the application's support team or call 1-800-MEDICARE (1-800-633-4227) |
the app is disabled by Blue Button 2.0 API administrator usually due to abnormal usage pattern etc., contact CMS as instructed, it is recommended to stop the app and resolve with Blue Button 2.0 API team |
|
| 404 NOT FOUND |
/v[12]/o/.* | Medicare is unable to retrieve your data at this time due to an internal issue. Our team is aware of the issue and is working to resolve it. Please try again at a later time. We apologize for any inconvenience. |
If any abnormality encountered during authorization, e.g. the patient is not found by mbi hash / hicn hash lookup, the message will be rendered as html page to the beneficiary, and with a 404 status code. the authorization process aborted. |
|
| 502 BAD GATEWAY |
/v[12]/o/.* | An error occurred connecting to medicare.gov account other additional messages: BBMyMedicareSLSxTokenException, or BBMyMedicareSLSxSignoutException, or BBMyMedicareSLSxValidateSignoutException, or BBMyMedicareCallbackAuthenticateSlsUserInfoValidateException, or BBMyMedicareSLSxUserinfoException at /mymedicare/sls-callback |
Abnormality encountered during authorization for various causes as indicated by error name in addition to the general message: An error occurred connecting to medicare.gov account |
|
| 500 SERVER ERROR |
/v[12]/o/.* | The root cause of the 500 error, some times, is indicated by the error message, the app can choose to retry the failed request depend on the nature of the root cause, examples that might be retriable are those related to network down (temporarily): Example: ConnectionError at /mymedicare/login HTTPSConnectionPool(host='test.accounts.cms.gov', port=443): Max retries exceeded with url: /health (Caused by NewConnectionError('<urllib3.connection.HTTPSConnection object at 0x7f46599dafd0>: Failed to establish a new connection: [Errno -2] Name or service not known')) |
App retry on request during authorization is not recommended. |
| Status Code | End Point URL | Error Message | Action | Comments |
|---|---|---|---|---|
| 400 BAD REQUEST |
/v[12]/fhir/.* | the response comes from FHIR data backend. Example message: details: IllegalArgumentException: Unsupported ID pattern |
Fix the request |
fhir request has invalid parameter(s) |
| 403 FORBIDDEN |
/v[12]/fhir/.* | You do not have permission to perform this action. | the request is not in the scope of the grant authorized, e.g. the beneficiary did not grant access to the demographic data |
|
| 403 FORBIDDEN |
/v[12]/fhir/.* | This application, {your app name}, is temporarily inactive. If you are the app maintainer, please contact the Blue Button 2.0 API team. If you are a Medicare Beneficiary and need assistance, please contact the application's support team or call 1-800-MEDICARE (1-800-633-4227) |
the app is disabled by Blue Button 2.0 API administrator usually due to abnormal usage pattern etc., contact CMS as instructed, it is recommended to stop the app and resolve with Blue Button 2.0 API team |
|
| 404 NOT FOUND |
/v[12]/fhir/.* | The requested resource does not exist | for example, for a fhir read request as: /v2/fhir/Patient/-1234567890 but there is not a patient with fhir_id = -1234567890, a 404 is returned |
|
| 502 BAD GATEWAY |
/v[12]/fhir/.* | An error occurred contacting the upstream server: Example: UpstreamServerException('An error occurred contacting the upstream server:Failed to call access method: java.lang.IllegalArgumentException: _lastUpdate lower bound has an invalid prefix') |
An error occurred in FHIR data backend when retrieving the resources, it could be client side error e.g. a malformed query parameter in the URL where the error code should be 400 BAD REQUEST, or a back end internal error. the action on the 502 error is on a case by case basis, e.g. if the root cause of the 502 is actually a bad query parameter, then retry is a sensible action. |
|
| 500 SERVER ERROR |
/v[12]/fhir/.* | The root cause of the 500 error, some times, is indicated by the error message, the app can choose to retry the failed request depend on the nature of the root cause, examples that might be retriable are those related to network down (temporarily): Example: ConnectionError at /mymedicare/login HTTPSConnectionPool(host='test.accounts.cms.gov', port=443): Max retries exceeded with url: /health (Caused by NewConnectionError('<urllib3.connection.HTTPSConnection object at 0x7f46599dafd0>: Failed to establish a new connection: [Errno -2] Name or service not known')) |
Heuristic on Retry | App can choose to retry on some of the 500 errors as shown by the example, this is a heuristic approach. |
Auto retrying (with sensible retry settings) on FHIR Data read/search to overcome a FHIR backend network temporary downtime is recommended.
Due to the involvement of the end user (beneficiary), auto retrying requests in the authorization flow are not recommended.