Fleet API Webhook callback response

개요

본 문서는 Fleet API Webhook callback response를 작성할 수 있도록 제공하는 가이드 문서입니다. 차량 및 fleet 데이터 전송 요청에 대해 클라이언트와 서버가 동일한 기준으로 응답 코드를 해석하고, 오류 발생 시 적절한 대응을 할 수 있도록 하기 위해 작성되었습니다.

HTTP 200번대 응답 코드 (성공 처리)

200 OK

• description:
  요청이 정상적으로 처리되어 결과 데이터가 즉시 응답 본문에 포함된 경우 사용합니다.
• use case:
  • 데이터 전송 요청에 대해 즉각적인 처리 결과(예: 요청 처리 완료 결과)를 전달할 때
• response_example:

  {
    "status": "completed",
    "message": "Request processed successfully."
  }
• notes:
  클라이언트는 이 응답을 통해 요청이 정상 수신되었음을 확인하고, 후속 확인 절차를 마련할 수 있습니다.

202 Accepted

• description:
  요청이 정상적으로 접수되었으나, 실제 처리는 비동기적으로 진행되는 경우에 사용합니다.
• use case:
  • 데이터 전송 요청이 큐에 등록되어 비동기 처리로 진행할 때
• response_example:

  {
    "status": "accepted",
    "message": "Request accepted. The result will be delivered via callback later.",
    "internal_code": 3000
  }
• notes:
  클라이언트는 이 응답을 통해 요청이 정상 수신되었음을 확인하고, 후속 확인 절차를 마련할 수 있습니다.

204 No Content

• description:
  요청이 성공적으로 처리되었으나, 응답 본문에 반환할 데이터가 없는 경우 사용합니다.
• use case:
  • 별도의 데이터 반환이 필요 없는 경우
• response_example:
  (HTTP 헤더에 성공 상태를 포함하며, 본문은 비어있음)
• notes:
  클라이언트는 HTTP 상태 코드만으로 성공 여부를 확인할 수 있습니다.

HTTP 400번대 응답 코드 (클라이언트 오류)

HTTP 400번대 응답 필드 설명

HTTP 400번대 응답 본문에 포함되는 주요 필드에 대한 설명은 다음과 같습니다.

error

• Description:
  HTTP 응답 상태 메시지를 간단하게 나타냅니다.
• Purpose:
  클라이언트가 발생한 오류의 종류를 빠르게 파악할 수 있도록 합니다.
• Example:
  "error": "Bad Request"

message

• Description:
  전체 오류 상황에 대한 요약 메시지를 제공합니다.
• Purpose:
  오류의 원인을 한 문장으로 설명하여 클라이언트가 문제의 전반적인 내용을 이해하도록 돕습니다.
• Example:
  "message": "Required fields are missing in the request."

errors

• Description:
  복수의 세부 오류 정보를 배열 형태로 제공하며, 각 항목은 개별 오류에 대한 상세 정보를 포함합니다.

• Purpose:
  요청 데이터 내 여러 필드에서 발생한 오류를 구체적으로 안내하여, 클라이언트가 어떤 부분을 수정해야 하는지 명확하게 합니다.

• Example:

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

  각 개별 오류 항목의 세부 구성:

  • field:
    • Description: 오류가 발생한 특정 요청 필드의 이름을 나타냅니다.
    • Purpose: 클라이언트가 어떤 필드에서 오류가 발생했는지 식별할 수 있도록 합니다.
    • Example: "field": "vin"
  • message (개별 항목):
    • Description: 해당 필드에서 발생한 오류의 상세 설명을 제공합니다.
    • Purpose: 오류의 구체적인 원인을 설명하여, 클라이언트가 문제를 쉽게 이해하고 수정할 수 있도록 돕습니다.
    • Example: "message": "This field is required."
  • code:
    • Description: 내부에서 정의한 오류 식별 코드로, 오류의 종류를 분류하는 데 사용됩니다.
    • Purpose: 문제 해결 및 디버깅을 위한 오류 유형 식별에 도움을 줍니다.
    • Example: "code": "ERR_MISSING_FIELD"

Syntax Error

• description:
  요청 데이터의 JSON 포맷이 올바르지 않거나, 구조적 오류가 있는 경우입니다.
• use case:
  • JSON 데이터에서 닫는 중괄호(})가 누락되는 등의 포맷 오류 발생 시
• response_example:

  {
    "error": "Bad Request",
    "message": "There is a syntax error in the request data."
  }
• notes:
  클라이언트는 데이터 포맷을 올바르게 수정하여 재전송해야 합니다.

Missing Required Fields

• description:
  차량 데이터 전송 요청에 반드시 포함되어야 하는 필드가 누락된 경우입니다.
• use case:
  • 필수 정보(예: 식별자, 타임스탬프, 위치 정보 등)가 누락된 경우
• 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:
  누락된 필드를 명시하고, 클라이언트가 수정 후 재전송할 수 있도록 안내합니다.

Validation Failure

• description:
  요청 데이터 내 값이 요구되는 형식이나 범위를 벗어난 경우입니다.
• use case:
  • 데이터 필드네임, 값이 사전 협의된 내용과 다른 경우
• 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:
  각 필드에 대해 올바른 형식과 범위를 상세히 안내하여, 클라이언트가 수정 후 재전송할 수 있도록 합니다.

HTTP 500번대 응답 코드 (서버 오류)

500 Internal Server Error

• description:
  서버 내부에서 예기치 않은 오류가 발생하여 요청을 처리할 수 없을 때 사용합니다.
• use case:
  • 코드 예외, 데이터베이스 연결 실패, 로직 오류 등이 발생한 경우
• response_example:

  {
    "error": "Internal Server Error",
    "message": "An internal server error occurred. Please try again later."
  }
• notes:
  구체적인 내부 정보는 노출하지 않고, 클라이언트에게 오류 발생 사실과 재시도 권고 메시지를 전달합니다.

503 Service Unavailable

• description:
  서버가 일시적으로 요청을 처리할 수 없는 상태임을 나타냅니다.
• use case:
  • 서버 과부하, 유지보수, 임시 네트워크 장애 등
• response_example:

  {
    "error": "Service Unavailable",
    "message": "The server is currently overloaded. Please try again later.",
    "retry_after": 30
  }
• notes:
  retry_after 필드를 통해 클라이언트가 재시도할 수 있는 시간을 안내합니다.

502 Bad Gateway / 504 Gateway Timeout (게이트웨이/프록시 오류)

• description:
  게이트웨이 또는 프록시 서버가 상위 서버로부터 유효한 응답을 받지 못했거나, 응답 대기 중 타임아웃이 발생한 경우에 사용됩니다.
• use case:
  • 502 Bad Gateway: 게이트웨이로부터 유효한 응답을 받지 못한 경우
  • 504 Gateway Timeout: 상위 서버의 응답을 대기하는 동안 타임아웃이 발생한 경우
• 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:
  • 이 오류들은 서버 간의 통신 문제로 발생하는 경우가 많으며, 클라이언트에게는 상위 서버인 게이트웨이의 문제임을 알리는 목적입니다.
  • 서버는 해당 오류 발생 시 내부 로그에 상세 정보를 기록하여 문제 원인을 분석하고, 게이트웨이의 연동 상태를 점검해야 합니다.