BetterDoctor Error Codes

Below is a full list of possible BetterDoctor REST API error codes.

HTTP code subset

The BetterDoctor API returns an appropriate HTTP status code for every request made, indicating success or failure of an API call. As a standard, HTTP status codes in the 2xx range means success, 4xx range means there was an error in the provided information, and those in the 5xx range indicates server side errors. The following table describes the HTTP status codes returned by the BetterDoctor API.

Code Description
200 OK / Success
400 Bad Request / Invalid or missing parameter
401 Unauthorized
405 Method not allowed
429 Too much traffic
500 Internal Server Error
503 Service unavailable

BetterDoctor error codes

In addition to the HTTP status codes, BetterDoctor API returns BetterDoctor error codes in the error message. The following table describes the codes that may appear in the BetterDoctor API error message.

Code Description Error text
1000 Authentication error auth_error
1100 Missing parameter missing_parameter
1101 Bad parameter bad_parameter
2001 Usage limit reached usage_limit_reached
9999 Unspecified unspecified

The description of the errors

Not all errors map cleanly onto HTTP status codes or BetterDoctor error codes. Below example of the JSON response in case of an error describes the error in detail. The JSON response constists of describing the error in both descriptive text based and code based manner. Descriptive, human-friendly fields are "message" and "details". The BetterDoctor error codes are stated as "error_code" and the HTTP status code will read as “http_status_code”.

      ErrorMessage {
        meta (ErrorMeta)
      }


      ErrorMeta {
        error (boolean): Always true; indicates that this message is an error header.
        message (string): Human readable error description. 
        error_code (integer, optional): BetterDoctor assigned error code. 
        http_status_code (integer, optional): The HTTP status code returned to the client. 
        details (string, optional): Optional JSON object describing the details of the error.
      }    

Error scenarios

The following examples describe different scenarios that may appear when working with the BetterDoctor API. The descriptive error text may change according to the end point, but the HTTP status codes and BetterDoctor error codes will remain the same for the same type of error.

400 - Bad parameter


Status code: 400
Error code: 1101
Message: "Bad request"
Details: Bad parameters for this endpoint. See documentation for the correct ones.


Response body

{
  "meta": {
   "error": true,
   "message": "At least one of the request parameters 'query', 'location', 'name', 'first_name', 'last_name' needs to be provided",
   "error_code": 1100,
   "http_status_code": 400
  }
}
	 

401 - Bad API key


Status code: 401
Error code: 1000
Message: “Invalid user_key”





Response body

{
  "meta": {
   "error": true,
   "message": "Invalid user_key",
   "error_code": 1000,
   "http_status_code": 401
  }
}
        

429 - Over the rate limit


Status code: 429
Error code: 9999
Message: "We have detected excessive traffic coming from this IP. Allowed: 40 request in 60 seconds. Minimum time between requests 0.5 seconds."
Details: Too much traffic.

Response body

{
  "meta": {
   "error": true,
   "message": "We have detected excessive traffic coming from this IP. Allowed: 40 request in 60 seconds. Minimum time between requests 0.5 seconds.",
   "error_code": 9999,
   "http_status_code": 429
  }
}
        

404 - Not found


Status code: 404
Error code: 9999
Message: "We were unable to fill the prescription"
We were unable to fill the prescription.


Response body

{
  "meta": {
   "error": true,
   "message": "We were unable to fill the prescription",
   "error_code": 9999,
   "http_status_code": 404
  }
}
	 

405 - Querying bad endpoint


Status code: 405
Error code: 9999
Message: "Method not allowed"
Details: Method not allowed for this endpoint. See headers for allowed methods.

Response body

{
  "meta": {
   "error": true,
   "message": "Document not found",
   "error_code": 9999,
   "http_status_code": 404
  }
}
	

500 - Internal server error


Status code: 500
Error code: 9999
Message: "Server error"
Details: Server error.



Response body

{
  "meta": {
   "error": true,
   "message": "Server error",
   "error_code": 9999,
   "http_status_code": 500
  }
}
	

Immediate access to API keys