🚨 Error Handling in the ShipGenius GraphQL API

Consistent, structured error responses for better developer experience

📘 Overview

GraphQL error handling differs significantly from REST. In our API, you will always receive a 200 OK response from the server unless an internal server error occurs (which results in a 500). This behavior aligns with the GraphQL specification.

To provide more familiar REST-like semantics, we include an http_status field and a code string within the extensions object of each error.

The http_status reflects the HTTP-style status code relevant to the error.

The code is a short, human-readable string identifier for the error, they are intended for internal categorization and client-side handling.

🔍 Response Format

A typical GraphQL response may contain data and/or errors keys. Depending on the operation, one or both may be present:

• ✅ Successful request: data is populated, errors is empty or absent.
• ⚠️ Partial failure: data may be partially filled, errors is present.
• ❌ Complete failure: data: null, errors contains one or more errors.

{
  "data": null,
  "errors": [
    {
      "message": "No valid shipment found. Either there is no shipment with the specified identifiers, it has already been used or voided, or it is over a month old.",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": ["void_shipment"],
      "extensions": {
        "http_status": 400,
        "code": "Invalid Request",
        "additional_details": {}
      }
    }
  ]
}

🔑 extensions Fields

Field	Type	Description
http_status	number	Simulated REST-like HTTP status (e.g. 400, 404, 403, 422, 500)
code	string	Stable error category (e.g. Invalid Request, Not Found, DUPLICATE_REQUEST_ID) for driving error recovery logic
additional_details	object	Extra metadata that may help resolve the issue (e.g. the value that couldn't be found)

🧰 Common Error Codes

http_status	Description
400	Malformed input, bad arguments, or missing fields
401	Invalid Authorization
404	Resource not found (shipment, label, etc.)
403	No Access to Requested Resource
409	Resource conflict (e.g., label already voided)
500	Unexpected failure—please report this to our team

🛠 Internal Logging

If something looks off or you receive a 500, please reach out to info@shipgeni.us with the logger_id in the extensions.

🧪 Tips for Debugging

• Always inspect the errors[0].extensions.code for actionable insight.
• The errors[0].message will be the human-readable information explaining the error.
• Use the path field to locate which part of your query caused the failure.
• Look at additional_details for structured error information.