Skip to main content

​
Error format

{
  "data": null,
  "errors": [
    {
      "message": "Human-readable error description",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["products", "edges", 0, "node"],
      "extensions": {
        "code": "ERROR_CODE",
        "requestId": "req_abc123"
      }
    }
  ]
}

​
Error codes

​
Authentication & Authorization

CodeDescription
UNAUTHENTICATEDMissing or invalid API key
INVALID_API_KEYAPI key is malformed or revoked
FORBIDDENAPI key lacks required permissions or tier

​
Validation

CodeDescription
VALIDATION_ERRORInput validation failed
INVALID_ARGUMENTInvalid argument value
REQUIRED_FIELDRequired field is missing
INVALID_FORMATField format is incorrect

​
Resources

CodeDescription
NOT_FOUNDRequested resource does not exist
ALREADY_EXISTSResource with this identifier already exists
DEPENDENCY_ERROROperation depends on a missing or invalid resource

​
Rate Limiting & Quotas

CodeDescription
RATE_LIMIT_EXCEEDEDToo many requests
QUOTA_EXCEEDEDDaily quota exceeded

​
Server

CodeDescription
INTERNAL_ERRORUnexpected server error
SERVICE_UNAVAILABLEService temporarily unavailable
RENDER_TIMEOUTVisualisation rendering timed out
CALCULATION_ERRORImpact calculation failed

​
Partial success

GraphQL can return partial data alongside errors: 
{
  "data": {
    "products": {
      "edges": [
        { "node": { "id": "prod_abc123", "name": "Product A", "impactScore": { "co2Equivalent": 12.4 } } }
      ]
    }
  },
  "errors": [
    {
      "message": "Failed to load impact score for product prod_def456",
      "path": ["products", "edges", 1, "node", "impactScore"],
      "extensions": { "code": "CALCULATION_ERROR" }
    }
  ]
}

​
Validation error details

{
  "errors": [
    {
      "message": "Validation failed",
      "extensions": {
        "code": "VALIDATION_ERROR",
        "details": {
          "fields": [
            { "field": "quantity", "message": "Must be greater than 0" },
            { "field": "transportMethod", "message": "Invalid value. Allowed: TRUCK, RAIL, SHIP, AIR" }
          ]
        }
      }
    }
  ]
}

​
Retry strategy

For RATE_LIMIT_EXCEEDED and SERVICE_UNAVAILABLE errors:
  1. Check extensions.retryAfter for the recommended wait time
  2. If not provided, use exponential backoff: 1s, 2s, 4s, 8s
  3. Maximum 5 retries