Skip to main content
The Kim360 API uses standard HTTP status codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate a client-side error (e.g., a problem with the request or authentication), and codes in the 5xx range indicate a server-side error.

​
Error Response Structure

When an error occurs, the API will respond with a JSON object containing details about the error. A typical error response follows this structure: 
{
  "statusCode": 400,
  "message": "Validation failed. See details.",
  "error": "Bad Request",
  "details": [
    {
      "field": "email",
      "message": "Email must be a valid email address."
    },
    {
      "field": "password",
      "message": "Password must be at least 8 characters long."
    }
  ]
}
Key Fields:
  • statusCode (integer): The HTTP status code for the error.
  • message (string): A human-readable summary of the error. This message is generally not suitable for programmatic parsing but can be helpful for debugging.
  • error (string): The standard HTTP status text (e.g., “Bad Request”, “Unauthorized”).
  • details (array of objects, optional): Provides specific information about what went wrong, often used for validation errors. Each object in the array might contain:
    • field (string): The specific input field that caused the error.
    • message (string): A detailed message about the error related to this field.
    • code (string, optional): A specific error code for programmatic handling.

​
Common HTTP Status Codes

Here are some of the common HTTP status codes you might encounter:

​
400 Bad Request

This code indicates that the server could not understand the request due to invalid syntax or missing required parameters. This is often due to issues with the request payload. Possible Causes:
  • Missing required fields in the request body.
  • Invalid data types (e.g., sending a string where a number is expected).
  • Malformed JSON.
Example: 
{
  "statusCode": 400,
  "message": "Missing required field: 'name'",
  "error": "Bad Request"
}

​
401 Unauthorized

This code means that the request has not been applied because it lacks valid authentication credentials for the target resource. Your API key might be missing, invalid, or expired. Possible Causes:
  • No API key provided in the Authorization header.
  • Invalid or revoked API key.
  • Expired API key or session token.
Example: 
{
  "statusCode": 401,
  "message": "Authentication token is missing or invalid.",
  "error": "Unauthorized"
}

​
403 Forbidden

This code indicates that the server understood the request but refuses to authorize it. This means you are authenticated, but you do not have permission to perform the requested action on the specified resource. Possible Causes:
  • The authenticated user does not have the necessary roles or permissions.
  • Trying to access a resource belonging to another user/account.
Example: 
{
  "statusCode": 403,
  "message": "You do not have permission to access this resource.",
  "error": "Forbidden"
}

​
404 Not Found

This code means that the server cannot find the requested resource. URLs are case-sensitive. Possible Causes:
  • The requested URL or endpoint does not exist.
  • The resource identified by a parameter (e.g., an ID in the URL path) does not exist.
Example: 
{
  "statusCode": 404,
  "message": "The requested resource with ID '123xyz' was not found.",
  "error": "Not Found"
}

​
429 Too Many Requests

This code indicates that the user has sent too many requests in a given amount of time (“rate limiting”). Check the Retry-After header for information on when to retry the request. Possible Causes:
  • Exceeding the API rate limits for your account or API key.
Example: 
{
  "statusCode": 429,
  "message": "Rate limit exceeded. Please try again later.",
  "error": "Too Many Requests"
}

​
500 Internal Server Error

This code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request. This is a generic error message when no more specific message is suitable. These errors should be reported to Kim360 support if they persist. Possible Causes:
  • An unhandled exception occurred on the server.
  • A problem with a downstream service or database.
Example: 
{
  "statusCode": 500,
  "message": "An unexpected error occurred on the server.",
  "error": "Internal Server Error"
}

​
Best Practices for Error Handling

  1. Check the HTTP Status Code: Always check the status code of the response before attempting to parse the body.
  2. Parse the Error Response: If an error occurs (4xx or 5xx status code), parse the JSON error response to get more details.
  3. Implement Retries (with backoff): For transient errors like 429 Too Many Requests or 5xx server errors, implement a retry mechanism with an exponential backoff strategy to avoid overwhelming the server.
  4. Log Errors: Log detailed error information, including the request made and the full error response received, to help with debugging.
  5. Handle Specific Error Details: For validation errors (400 Bad Request), use the details array to provide specific feedback to the user or to guide programmatic corrections.
  6. Do Not Expose Sensitive Information: Ensure your client-side error handling does not expose sensitive information from error messages.
By understanding these error codes and following these best practices, you can build more resilient and user-friendly integrations with the Kim360 API.