|
| 1 | +# Blue Button 2.0 API Error Responses |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +This document serves as a supplementary to Blue Button 2.0 API Developer Documents, it gives more details on most commonly error responses and recommended error handling on the client side, e.g. guide lines on retrying the requests on certain errors. |
| 6 | + |
| 7 | +## Error Responses and Client Actions |
| 8 | + |
| 9 | +### Authorization Requests |
| 10 | + |
| 11 | + |
| 12 | +| Status Code | End Point URL | Error Message | Action | Comments | |
| 13 | +| -------------- | --------------- | -------------------------- | ----------------- | ------------------------------------------------------ | |
| 14 | +| 400<br>BAD REQUEST | /v[12]/o/.* | the response comes from blue button.<br>Example message:<br>error: unsupported grant type | Report, No Retry<br>Fix the request<br> | request has invalid parameter(s) | |
| 15 | +| 403<br>FORBIDDEN | /v[12]/o/authorize/<br>/v[12]/o/authorize/(?P<uuid>[\w-]+)/$<br>/v[12]/o/token | You do not have permission to perform this action. | Report, No Retry | request does not pass permission check | |
| 16 | +| 403<br>FORBIDDEN | /v[12]/o/authorize/<br>/v[12]/o/authorize/(?P<uuid>[\w-]+)/$ | This application, {your app name}, is temporarily inactive. <br>If you are the app maintainer, please contact the Blue Button 2.0 API team. <br>If you are a Medicare Beneficiary and need assistance, please contact the application's support team <br>or call 1-800-MEDICARE (1-800-633-4227) | Report, No Retry | the app is disabled by Blue Button 2.0 API administrator usually <br>due to abnormal usage pattern etc., contact CMS as instructed, <br>it is recommended to stop the app and resolve with Blue Button 2.0 API team | |
| 17 | +| 404<br>NOT FOUND | /v[12]/o/.* | Medicare is unable to retrieve your data at this time due to an internal issue.<br>Our team is aware of the issue and is working to resolve it.<br>Please try again at a later time. We apologize for any inconvenience. | Report, No Retry | If any abnormality encountered during authorization, e.g. <br>the patient is not found by mbi hash / hicn hash lookup, the message will be <br>rendered as html page to the beneficiary, and with a 404 status code.<br>the authorization process aborted. | |
| 18 | +| 502<br>BAD GATEWAY | /v[12]/o/.* | An error occurred connecting to medicare.gov account<br><br>other additional messages:<br><br>BBMyMedicareSLSxTokenException, or<br>BBMyMedicareSLSxSignoutException, or<br>BBMyMedicareSLSxValidateSignoutException, or<br>BBMyMedicareCallbackAuthenticateSlsUserInfoValidateException, or<br>BBMyMedicareSLSxUserinfoException at /mymedicare/sls-callback | Report, No Retry | Abnormality encountered during authorization for various causes as indicated by <br>error name in addition to the general message:<br><br>An error occurred connecting to medicare.gov account |
| 19 | + | |
| 20 | +| 500<br>SERVER ERROR | /v[12]/o/.* | The root cause of the 500 error, some times, is indicated by the error message, <br>the app can choose to retry the failed request depend on the nature of the root cause, <br>examples that might be retriable are those related to network down (temporarily):<br>Example:<br>ConnectionError at /mymedicare/login<br>HTTPSConnectionPool(host='test.accounts.cms.gov', port=443): <br>Max retries exceeded with url: /health (Caused by NewConnectionError('<urllib3.connection.HTTPSConnection object at 0x7f46599dafd0>: <br>Failed to establish a new connection: [Errno -2] Name or service not known')) | Report, Retry not recommended | App retry on request during authorization<br>is not recommended. | |
| 21 | + |
| 22 | + |
| 23 | +### Data Requests |
| 24 | + |
| 25 | + |
| 26 | +| Status Code | End Point URL | Error Message | Action | Comments | |
| 27 | +| -------------- | --------------- | -------------------------- | ----------------- | ------------------------------------------------------ | |
| 28 | +| 400<br>BAD REQUEST | /v[12]/fhir/.* | the response comes from FHIR data backend.<br>Example message:<br>details: IllegalArgumentException: Unsupported ID pattern | Report, No Retry<br>Fix the request<br> | fhir request has invalid parameter(s) | |
| 29 | +| 403<br>FORBIDDEN | /v[12]/fhir/.* | You do not have permission to perform this action. | Report, No Retry | the request is not in the scope of the grant authorized, <br>e.g. the beneficiary did not grant access to the demographic data | |
| 30 | +| 403<br>FORBIDDEN | /v[12]/fhir/.* | This application, {your app name}, is temporarily inactive. <br>If you are the app maintainer, please contact the Blue Button 2.0 API team. <br>If you are a Medicare Beneficiary and need assistance, please contact the application's support team <br>or call 1-800-MEDICARE (1-800-633-4227) | Report, No Retry | the app is disabled by Blue Button 2.0 API administrator usually <br>due to abnormal usage pattern etc., contact CMS as instructed, <br>it is recommended to stop the app and resolve with Blue Button 2.0 API team | |
| 31 | +| 404<br>NOT FOUND | /v[12]/fhir/.* | The requested resource does not exist | Report, No Retry | for example, for a fhir read request as:<br>/v2/fhir/Patient/-1234567890<br>but there is not a patient with<br>fhir_id = -1234567890, a 404 is returned | |
| 32 | +| 502<br>BAD GATEWAY | /v[12]/fhir/.* | An error occurred contacting the upstream server: <error details><br>Example:<br>UpstreamServerException('An error occurred contacting the upstream server:Failed to call access method: <br>java.lang.IllegalArgumentException: _lastUpdate lower bound has an invalid prefix') | Report, No Retry | An error occurred in FHIR data backend when retrieving the resources, <br>it could be client side error e.g. a malformed query parameter in the URL where the error code should be 400 BAD REQUEST, <br>or a back end internal error.<br>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, <br>then retry is a sensible action. | |
| 33 | +| 500<br>SERVER ERROR | /v[12]/fhir/.* | The root cause of the 500 error, some times, is indicated by the error message, <br>the app can choose to retry the failed request depend on the nature of the root cause, <br>examples that might be retriable are those related to network down (temporarily):<br>Example:<br>ConnectionError at /mymedicare/login<br>HTTPSConnectionPool(host='test.accounts.cms.gov', port=443): <br>Max retries exceeded with url: /health (Caused by NewConnectionError('<urllib3.connection.HTTPSConnection object at 0x7f46599dafd0>: <br>Failed to establish a new connection: [Errno -2] Name or service not known')) | Report, Heuristic on Retry | App can choose to retry on some of the 500 errors as shown by the example, this is a heuristic approach. | |
| 34 | + |
| 35 | + |
| 36 | +### Retry |
| 37 | + |
| 38 | +App can choose to retry the requests on certain 500 errors heuristically depending on the root cause as indicated by the error messages, e.g. backend server is unavailable due to temporarily network down etc., the app can choose from various retry patterns that best fits the use case (e.g. exponential back off). |
| 39 | + |
| 40 | +Auto retrying on FHIR Data read/search to overcome a FHIR backend network temporary downtime is recommended, but with sensible retry settings. |
| 41 | + |
| 42 | +Due to the involvement of end user (beneficiary), auto retrying on requests in an authorization flow does not seem practical, hence not recommended. |
0 commit comments