Error Handling

This section describes how UEAT’s Open API manages errors across all endpoints. Proper error handling ensures partners can diagnose issues quickly and maintain reliable integrations.

General Principles

All errors are returned in JSON format.
HTTP status codes indicate the type of error (system vs functional).
Detailed error objects provide actionable information.

HTTP Status Codes

Code	Meaning
200	Success
400	Bad Request (invalid input)
401	Unauthorized (invalid API key)
403	Forbidden (insufficient rights)
404	Not Found
409	Conflict (duplicate resource)
429	Too Many Requests (rate limit)
500	Internal Server Error

Error Object Structure

{
  "errors": [
    {
      "code": "INVALID_PAYLOAD",
      "message": "The request body is missing required fields.",
      "details": {
        "field": "locationId",
        "expected": "GUID"
      }
    }
  ]
}

Fields

code: Short identifier for the error.
message: Human-readable description.
details: Optional object with additional context.

Types of Errors

System Errors: Timeouts, authentication failures, server issues.
Functional Errors: Invalid payloads, missing fields, unsupported operations.

Best Practices

Always log the full error response.
Retry only on system errors (e.g., timeouts).
Validate payloads before sending to minimize functional errors.
Make sure each errors provide the required fields details to be actionable.

Example Scenarios

{
  "errors": [
    {
      "code": "INVALID_LOCATION",
      "message": "The provided locationId does not exist.",
      "details": "locationId 123 does not exist."
    }
  ]
}

Failed Order Creation

{
  "errors": [
    {
      "code": "MISSING_FIELD",
      "message": "The request body is missing required fields.",
      "details": {
        "field": "locationId",
        "expected": "GUID"
      }
    }
  ]
}

Most common Use Cases

Here are some use case where detailed response will help the support team and reduce escalation.

POS ID does not exist

{
  "errors": [
    {
      "code": "INVALID_ID",
      "message": "The provided POS ID does not exist.",
      "details": "POS ID from the payload."
    }
  ]
}

Order is outside of opening hours

{
  "errors": [
    {
      "code": "REJECTED_ORDER",
      "message": "The POS could not accept the order.",
      "details": "The order PickupDateTime is outside of the opening hours."
    }
  ]
}

Order price overwrite is exceeding limit

{
  "errors": [
    {
      "code": "INVALID_TOTAL",
      "message": "The POS could not accept the order.",
      "details": "The order price overwrite is exceeding limit."
    }
  ]
}

POS is Offline

{
  "errors": [
    {
      "code": "POS_OFFLINE",
      "message": "The POS could not accept the order.",
      "details": "Order rejected. POS is Offline."
    }
  ]
}

Invalid API Key

In the acknowledge response

{
  "errors": [
    {
      "code": "INVALID_API_KEY",
      "message": "Unauthorized. Invalid API Key.",
    }
  ]
}

Table of Contents