Error handling

Learn how to interpret and manage errors returned by the API.

When your API request is successful, you will receive an HTTP successful response code (any code between 200 and 299) along with the requested data (if applicable). However, if your request fails, the error response will include three key elements:

1. An HTTP code: A standard HTTP status code indicating the error type. For a complete list of HTTP status codes, refer to MDN Web Docs ↗.
2. An error code: A machine-readable identifier for the error provided in the JSON response, formatted in camelCase. For example:
   • "code": "badMediaType"
   • "code": "userNotFound"
3. An error message: A human-readable description of the error in the JSON response, which may include dynamic placeholders for contextual information. For example:
   • "message": "The {{step_type}} step with _id {{step_id}} is duplicated in the payload."
   • "message": "The given pathId does not correspond to any existing path."

Understanding these components will help you identify, handle, and debug issues effectively.

Handling errors

When you encounter an error:

1. Check the HTTP status code to identify the type of issue:
   • Client-side errors (400-499): Indicate problems like malformed requests or unauthorized access.
   • Server-side errors (500-599): Indicate problems with the server processing the request.
2. Use the error "code" in the JSON response to pinpoint the specific error and handle it programmatically.
3. Review the error "message" in the JSON response for additional context and details to correct the request.

Special cases

Some errors may not follow the usual structure. In these cases, the JSON response will not include an error "code" or "message" but instead will contain an "error" field, providing a general description of the problem. For more information, see:

• Authentication errors
• Scope errors
• Rate limiting errors