When something goes wrong with an API request because of an issue with the API call or Merit's servers, the Merit API will respond with a 4xx or 5xx HTTP status code and information about what went wrong.

When something goes wrong with an API request the Merit API will respond with an appropriate HTTP status code. Errors caused by issues with the request itself will return 4xx status codes, while errors caused by errors on Merit's servers will return 5xx status codes. Successful requests will always return 2xx status codes.

Responses with 4xx error codes will always include the following information:

  • error_code: A short string identifying the type of error
  • message: A short message in English explaining the error and how to resolve it
  • doc_url: A link to an explanation of the error with information on how to resolve it

For certain error codes the error response will also include structured information about the error to allow you to programmatically resolve the error.

  "error_code": "NotFound",
  "message": "No Merit was found for Merit ID 573564e698ae3b96668fd517",
  "doc_url": ""

Error Codes

Error CodeWhat This MeansWhat To Do
NotFoundReturned when requests refer to one or more IDs that appear valid but does not correspond to objects in Merit.The error message should provide information on which ID was invalid. You'll need to check your code to see where things went wrong.
AppRateLimitYour request exceeded your App's rate limit.Wait and try again using the techniques described here.


Your code should not assume that the error codes listed here are the only ones that can ever be returned. Additional error codes that don't represent new functionality may be added without the introduction of new versions.