TEST - Error Response Structure | DOCS

Overview

The SweetConnect Platform API uses a structured, consistent error response format across all endpoints. Every error response contains detailed information to help you identify and resolve issues quickly.

Error Response Format

All error responses follow this structure:

{
  "errors": [
    {
      "errorCode": "FileTooLarge",
      "message": "Uploaded file exceeds the maximum allowed size of 10MB. Current file size: 12.5MB.",
      "extension": {
        "maxFileSize": 10,
        "currentFileSize": 12.5
      }
    }
  ]
}

Response Structure

Field	Type	Description
`errors`	Array	List of error objects (can contain multiple errors)
`errorCode`	String	Machine-readable error identifier - use this to handle specific errors programmatically
`message`	String (optional)	Human-readable error description
`extension`	Object (optional)	Additional structured data providing context about the error

HTTP Status Codes

Errors are returned with appropriate HTTP status codes:

Status Code	Meaning	Example Error Codes
400 Bad Request	Invalid input or request	`BadRequest`, `FileTooLarge`, `InvalidMimeType`, `InvalidLanguageCode`
401 Unauthorized	Authentication required or failed	`Unauthorized`, `InvalidToken`
403 Forbidden	Insufficient permissions	`NoPermission`
404 Not Found	Resource doesn't exist	`NotFound`
409 Conflict	Resource conflict	`Conflict`, `SerialNumberAlreadyExists`
500 Internal Server Error	Server-side error	`InternalServerError`

Error Code Identification

The errorCode field is your primary tool for programmatically handling errors. It provides a consistent, machine-readable identifier that won't change between API versions.

Why Use Error Codes?

✅ Do this:

if (response.errors[0].errorCode === 'FileTooLarge') {
  // Handle file too large error
  const maxSize = response.errors[0].extension.maxFileSize;
  alert(`Please upload a file smaller than ${maxSize}MB`);
}

❌ Don't do this:

// Don't parse message strings - they may change!
if (response.errors[0].message.includes('file exceeds')) {
  // Fragile - message text may change
}

Multiple Errors

A single API response can contain multiple errors when multiple validation issues are detected:

{
  "errors": [
    {
      "errorCode": "InvalidLanguageCode",
      "message": "Language code 'xyz' is not valid",
      "extension": {
        "languageCode": "xyz",
        "validLanguageCodes": ["en", "de", "fr", "es", "it"]
      }
    },
    {
      "errorCode": "FileTooLarge",
      "message": "Uploaded file exceeds the maximum allowed size of 10MB. Current file size: 12.5MB.",
      "extension": {
        "maxFileSize": 10,
        "currentFileSize": 12.5
      }
    }
  ]
}

Benefits:

Fix all issues at once instead of one-by-one
Better user experience - show all validation errors together
Fewer API round-trips

Extension Objects

The extension field provides structured, actionable data about the error. Use this to build intelligent error handling and user feedback.

File Size Error Example

{
  "errorCode": "FileTooLarge",
  "extension": {
    "maxFileSize": 10,
    "currentFileSize": 12.5
  }
}

What you can do:

Display file size limit before upload
Show exact size vs limit: "12.5MB / 10MB"
Calculate percentage: "125% of allowed size"

Asset Type Constraint Example

{
  "errorCode": "AssignAssetTypeConstraint",
  "extension": {
    "assetType": "machine",
    "parentAssetType": "component",
    "allowedParentAssetTypes": ["production-line", "location"]
  }
}

What you can do:

Filter dropdown to show only allowed parent types
Display: "machines can only be assigned to production-line or location"
Prevent invalid selections in UI

Next Steps

Success Response Structure - Understanding successful responses

Error Response Structure

On this page