Error Handling

Errors encountered while interacting with the Moz API are returned with the appropriate HTTP status code and contain metadata along with detailed error information in the response body. This guide provides an overview of common errors and their explanations, along with information on rate limiting and handling interdependent parameters.

Error Response Structure

Error responses contain the following components:

• Metadata:

  • id: Echo of the ID provided by the client in the request.
  • jsonrpc: JSONRPC version of the API.

• Error Object:

  • code: Internal API error code.
  • status: HTTP error status code.
  • data: For more complex errors, this object will contain additional information about the error:
  • explanation: Explains why the error occurred
  • issue: Identifies the family of error
  • key: Identifies the component of the request that caused the error

• message: Serves the purpose of the "explanation" field in simple errors and/or gives instructions on how to resolve the error

Here is an example of the JSON body of an error response returned by the Moz API:

{
  "id": "c6c90a58-34b6-4a4b-85d5-021c8c363a63",
  "jsonrpc": "2.0",
  "error": {
    "code": -32652,
    "status": 400,
    "data": {
      "explanation": "query is a required field and was not included.",
      "issue": "param-is-missing",
      "key": "query"
    },
    "message": "Please include a query"
  }
}

Rate Limiting

Users who send more than 50 requests in a 5-minute period resulting in a 4xx error code will be rate-limited to a rate of 50 total requests per 5-minute period. The rate limit will be lifted after 30 seconds without receiving 4xx responses.

Interdependent Parameters

Some methods may have interdependent parameters, where certain combinations of parameters are not accepted or use of one optional parameter must be paired with the use of a second optional parameter. While efforts have been made to minimize this in our API design and you shouldn’t have to deal with it often if ever, if you do encounter an error regarding parameter compatibility, the error message in the response body will provide clarity on the required changes. Alternatively, refer to the method documentation for guidance on parameter usage.