API Error Codes

This document provides information about the error codes returned by our API. Understanding these error codes will help you troubleshoot issues and handle errors effectively in your application.

HTTP Status Codes

Our API uses standard HTTP status codes to indicate the success or failure of requests. Here are the main error status codes you may encounter:

Status Code	Description
400	Bad Request
401	Unauthorized
422	Unprocessable Entity (Client Error)
500	Internal Server Error

Error Response Structure

When an error occurs, the API returns a JSON object with the following fields:

Field	Data Type	Description
code	string	Application-level error code
status	int32	HTTP status code
message	string	Developer-friendly error message
requestId	string	Unique identifier for the request (used for tracing)
details	array of objects	Additional details about the error
details.key	string	Indicates the type of problem
details.description	string	Human-readable explanation specific to this occurrence of the problem

Example Error Response

{
  "code": "common_1",
  "status": 400,
  "message": "Asset ID not found.",
  "requestId": "79104EXAMPLEB723",
  "details": [
    {
      "key": "asset_id",
      "description": "The provided asset ID does not exist in our system"
    }
  ]
}

Common Error Scenarios

400 Bad Request

This error occurs when the request is malformed or contains invalid parameters. Possible reasons include:

• Missing required fields
• Invalid data formats
• Unsupported API version

401 Unauthorized

This error indicates that authentication has failed or has not been provided. Possible reasons include:

• Missing or invalid API key
• Expired authentication token
• Insufficient permissions for the requested resource

422 Client Error (Unprocessable Entity)

This error suggests that the server understands the content type of the request but was unable to process the contained instructions. Possible reasons include:

• Validation errors
• Business logic conflicts
• Unsupported operations

500 Server Error

This error indicates an unexpected condition on the server that prevented it from fulfilling the request. Possible reasons include:

• Server-side bugs
• Database issues
• Third-party service failures

Handling Errors

When encountering errors, we recommend the following best practices:

1. Always check the HTTP status code of the response.
2. Parse the error response JSON to extract detailed information.
3. Log the requestId for easier troubleshooting and support.
4. Implement appropriate error handling and retry mechanisms in your application.
5. For persistent issues, contact our support team and provide the requestId.

By following these guidelines and understanding the error codes, you can create a more robust and user-friendly integration with our API.