When integrating with our API, robust error handling is essential for a seamless user experience and resilient application performance. By addressing errors effectively, your application can gracefully manage issues, minimize disruptions, and maintain responsiveness.

Key steps include:

• Leveraging our standardized error response model.
• Keeping your error-handling logic up-to-date to adapt to any API changes.

Error Response Model

Our APIs return a structured error object for all errors to simplify issue diagnosis. The format is as follows:

{  
   "code":"<error_code>",  
   "title":"<error_title>",  
   "message":"<error_message>"  
}

Field Definitions:

• code: A unique, stable identifier for the error.
• title: A brief summary of the issue.
• message: Detailed guidance for resolving the error.

Field-Level Error Details

For issues specific to individual fields, a fields object provides additional context.

Examples:

{  
   "code":"0009",  
   "title":"Missing Fields in Request",  
   "message":"Your request is missing one or more required fields. Please refer to the documentation to ensure all necessary fields are included in your request.",  
   "fields": {  
      "{{field}}": "{{field}} is a required field"  
   }  
} 

{  
   "code":"0047",  
   "title":"Bad Request",  
   "message":"The server could not understand the request due to malformed syntax. Please check the listed fields and try again.",  
   "fields":{  
      "legalName": "legalName is a required field.",  
      "parentOrganizationId":"parentOrganizationId must be a valid UUID"  
   }  
}  

{  
   "code":"0053",  
   "title":"Unexpected Fields in the Request",  
   "message":"The request body contains more fields than expected. Please send only the allowed fields as per the documentation. The unexpected fields are listed in the fields object.",  
   "fields":{  
      "{{field}}":"{{error_message}}"  
   }  
}

Best Practices for Handling API Errors

1. Focus on Error Codes

• Error codes are stable and ideal for reliable handling logic.
• Map error codes to specific resolutions to ensure compatibility with API updates.

2. Log and Inform

• Log errors for monitoring and troubleshooting.
• Provide clear, actionable feedback to users with suggestions for resolution.

3. Stay Updated

• Regularly review error code documentation to align with new or updated conditions.
• Keep error-handling logic adaptable to future changes.

Adhering to these practices ensures a robust integration and an exceptional user experience.