Localization

Implement internationalization by parsing the Accept-Language header sent with every Xentral request. Localize user-facing content like field names, descriptions, and error messages while maintaining consistent identifiers across all locales.

Availability

Uptime

Maintain high service availability especially during business hours to ensure reliable label generation for Xentral users. Recommendations:

• Set up synthetic monitoring to test critical endpoints every 60 seconds
• Configure alerts for response times exceeding 5 seconds
• Monitor error rates above 1% for immediate escalation
• Track carrier API dependency health and response times
• Return meaningful error messages when services are unavailable

Throughput

Design your service to handle peak shipping volumes, especially during holiday seasons and promotional periods.

• Response Time: < 2 seconds for label generation requests
• Concurrent Requests: Support minimum 10 concurrent label creations per customer
• Peak Capacity: Expect to handle 10x more traffic during black friday or holiday seasons

Error Handling

Return structured error responses using HTTP status codes and standardized JSON payloads. Use this format to communicate validation failures and business rule violations:

{
  "type": "[identifier]",
  "title": "Request payload validation failed.",
  "violations": [
    {
      "username": [
        "This value should not be blank."
      ],
      "email": [
        "This value is not a valid email address."
      ]
    }
  ]
}

📘

Localization Required

All error messages are displayed directly to end users. Implement proper localization using the Accept-Language header and write user-friendly, actionable error messages.

Examples

Weight Limit Validation

{
  "type": "https://a-link-to-your-error-page.com/en/parcel-too-heavy",
  "title": "Parcel too heavy",
  "violations": [
    {
      "weight": [
        "The weight of the parcel must not exceed 5 kilograms. Please select a different shipping method, or create multiple parcels that each weigh less than 5kg."
      ],
    }
  ]
}

{
  "type": "https://a-link-to-your-error-page.com/de/parcel-too-heavy",
  "title": "Paket zu schwer",
  "violations": [
    {
      "weight": [
        "Das Paketgewicht darf 5 Kilogramm nicht überschreiten. Bitte wählen Sie eine andere Versandart oder erstellen Sie mehrere Pakete, die jeweils weniger als 5 Kilogramm wiegen."
      ],
    }
  ]
}