Skip to main content

Fleet API Webhook callback response

Overview​

This document provides a guide for writing the Fleet API Webhook callback response. It is written to ensure that the client and server interpret response codes consistently for vehicle and fleet data transmission requests and can handle errors appropriately.

HTTP 2xx Response Codes (Success)​

200 OK​

  • description:
    Used when the request is successfully processed and the result data is included in the response body immediately.
  • use case:
    • When providing an immediate processing result (e.g., completion of request processing) for a data transmission request
  • response_example: 
    {
      "status": "completed",
      "message": "Request processed successfully."
    }
  • notes:
    The client can confirm successful receipt of the request and prepare follow-up verification procedures.

202 Accepted​

  • description:
    Used when the request is successfully received but the actual processing occurs asynchronously.
  • use case:
    • When a data transmission request is queued for asynchronous processing
  • response_example: 
    {
      "status": "accepted",
      "message": "Request accepted. The result will be delivered via callback later.",
      "internal_code": 3000
    }
  • notes:
    The client can confirm successful receipt of the request and prepare follow-up verification procedures.

204 No Content​

  • description:
    Indicates that the request was successfully processed, but there is no data to return in the response body.
  • Use case:
    • When no data needs to be returned
  • response_example:
    (Contains a success status in the HTTP header, with an empty body)
  • notes:
    The client can determine success based on the HTTP status code alone.

HTTP 4xx Response Codes (Client Errors)​

HTTP 4xx Response Field Descriptions​

The following describes key fields included in HTTP 4xx response bodies.

Error​

  • Description:
    A brief representation of the HTTP response status message.
  • Purpose:
    Allows the client to quickly identify the type of error that occurred.
  • Example:
    "error": "Bad Request"

Message​

  • Description:
    Provides a summary message about the overall error situation.
  • Purpose:
    Summarizes the cause of the error in a single sentence, helping the client understand the problem.
  • Example:
    "message": "Required fields are missing in the request."

errors​

  • Description:
    Provides an array of detailed error information, where each item contains details about an individual error.

  • Purpose:
    Clearly identifies errors found in multiple fields of the request data, helping the client understand what needs to be corrected.

  • Example:

    "errors": [
      {
        "field": "vin",
        "message": "This field is required.",
        "code": "ERR_MISSING_FIELD"
      }
    ]

    Detailed structure of each error item:

    • field:
      • Description: Indicates the name of the specific request field where the error occurred.
      • Purpose: Helps the client identify which field caused the error.
      • Example: "field": "vin"
    • message (object):
      • Description: Provides a detailed explanation of the error that occurred in the field.
      • Purpose: Explains the specific cause of the error to help the client understand and fix the issue easily.
      • Example: "message": "This field is required."
    • code:
      • Description: An internally defined error identification code used to categorize the error type.
      • Purpose: Helps identify the type of error for troubleshooting and debugging.
      • Example: "code": "ERR_MISSING_FIELD"

Syntax Error​

  • description:
    This occurs when the JSON format of the request data is incorrect or has structural errors.
  • use case:
    • A format error occurs, such as a missing closing curly brace (}) in JSON data
  • response_example: 
    {
      "error": "Bad Request",
      "message": "There is a syntax error in the request data."
    }
  • notes:
    The client must correct the data format and resend the request.

Missing Required Fields​

  • description:
    This occurs when a required field is missing from the vehicle data transmission request.
  • use case:
    • Required information (e.g., identifier, timestamp, location data, etc.) is missing
  • response_example: 
    {
      "error": "Bad Request",
      "message": "Required fields are missing in the request.",
      "errors": [
        {
          "field": "field_name",
          "message": "This field is required.",
          "code": "ERR_MISSING_FIELD"
        }
      ]
    }
  • notes:
    Specifies the missing fields and instructs the client to correct and resend.

Validation Failure​

  • description:
    This occurs when a value in the request data does not meet the required format or range.
  • use case:
    • A data field name or value differs from the pre-agreed specification
  • response_example: 
    {
      "error": "Bad Request",
      "message": "Validation failed for the request data.",
      "errors": [
        {
          "field": "field_name",
          "message": "The value must be within a valid range.",
          "code": "ERR_INVALID_VALUE"
        }
      ]
    }
  • notes:
    Provides detailed guidance on the correct format and range for each field, allowing the client to correct and resend.

HTTP 5xx Response Codes (Server Errors)​

500 Internal Server Error​

  • description:
    Used when an unexpected server error occurs, preventing the request from being processed.
  • use case:
    • Occurs due to code exceptions, database connection failures, logical errors, etc.
  • response_example: 
    {
      "error": "Internal Server Error",
      "message": "An internal server error occurred. Please try again later."
    }
  • notes:
    Does not expose specific internal information while informing the client of the error and recommending a retry.

503 Service Unavailable​

  • description:
    Indicates that the server is temporarily unable to process the request.
  • Use case:
    • Server overload, maintenance, temporary network outage, etc
  • Response example: 
    {
      "error": "Service Unavailable",
      "message": "The server is currently overloaded. Please try again later.",
      "retry_after": 30
    }
  • notes:
    The retry_after field informs the client of the time to retry.

502 Bad Gateway / 504 Gateway Timeout (Gateway/Proxy Errors)​

  • description:
    Occurs when a gateway or proxy server fails to receive a valid response from an upstream server or times out while waiting for a response.
  • Use case:
    • 502 Bad Gateway: Failed to receive a valid response from the gateway
    • 504 Gateway Timeout: Timed out while waiting for the upstream server to respond
  • Response example (502 Bad Gateway): 
    {
      "error": "Bad Gateway",
      "message": "The upstream server did not send a valid response."
    }
  • Response example (504 Gateway Timeout): 
    {
      "error": "Gateway Timeout",
      "message": "The upstream server timed out while waiting for a response."
    }
  • Notes:
    • These errors often occur due to communication issues between servers and inform the client about a problem with the upstream server.
    • When this error occurs, the server should log detailed information internally for issue analysis and check the gateway's connection status.