🌐Base URL & Error Codes

This document provides the foundational information required to integrate with the UDAI API, covering hostnames, versioning, global middleware requirements, and common response/error formats.

Hostname

The UDAI API is available in multiple environments. Choose the appropriate environment depending on whether you're developing, testing, or working in production.

Environment	Base URL	Description
Production	https://api.udai.live	Live deployment environment
Staging	https://staging-api.udai.live	Used for testing and QA
Local	http://localhost:8000	Local development environment

Base-URL

All endpoints are prefixed with a base path after the hostname:

Base Path: /v1

So, a full endpoint URL looks like this:

GET https://api.udai.live/v1/drones

Versioning (/v1)

• The v1 in the base path indicates that this is the initial version of the UDAI API.

• Future upgrades (like /v2) may include new features or breaking changes while maintaining backward compatibility for older clients using v1.

Authentication & Headers

All authentication (partner-api-key, Authorization) and contextual routing (X-Organization-ID) logic is handled via Global API Middleware.

👉 Refer to the Global Security & Context Middleware in Access Control for detailed specifications on required headers for every request.

---

Error Response Format

Every API endpoint in this system uses a unified error response structure and a consistent set of HTTP status codes. All errors return JSON in this shape:

{
  "error": "Bad Request",
  "message": "Missing required field 'email'",
  "status_code": 400,
  "timestamp": "2025-07-17T11:45:00Z",
  "path": "/v1/auth/register"
}

Field	Type	Description
error	string	One-word error type (e.g. Unauthorized)
message	string	Human-readable explanation of what went wrong
status_code	int	Standard HTTP status code
timestamp	timestamp	ISO 8601 timestamp of the error
path	string	Endpoint where the error occurred

HTTP Status Codes

Global Codes (Middleware Executed)

These are handled at the gateway layer and apply globally to all restricted endpoints:

Code	Meaning	When
401	Unauthorized	Invalid/missing API key or JWT token
403	Forbidden	Authenticated but not authorised for this action (e.g. invalid X-Organization-ID RBAC)
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server failure
503	Service Unavailable	Database/server temporarily down or overloaded

Endpoint Codes

These codes depend heavily on the business context and are explicitly documented in the Responses section of every API endpoint in the documentation:

• 200 OK — Success (GET, PUT, DELETE)

• 201 Created — Resource was successfully created (POST)

• 400 Bad Request — Invalid request body, parameters, or business logic rule violation

• 404 Not Found — Missing UUID or resource

• 409 Conflict — Duplicate entry or state collision

• 422 Unprocessable Entity — Valid payload format, but invalid references (e.g., Drone Model UUID not permitted for Payload UUID)

---

Global Pagination Envelope

For all high-throughput endpoints that return lists of items (e.g., flight logs, drones, users), the UDAI API uses a standardized paginated response envelope structure.

Request (via Query Parameters):

Parameter	Type	Description	Default
page	integer	Page number to retrieve (starts from 1)	1
limit	integer	Number of records per page (e.g., 10, 25, 50)	25

Successful Pagination Response (200 OK):

{
  "message": "Resources retrieved successfully",
  "data": [
    { /* object 1 */ },
    { /* object 2 */ }
  ],
  "pagination": {
    "total_records": 142,
    "total_pages": 3,
    "current_page": 1,
    "per_page": 50,
    "has_next": true,
    "has_previous": false
  }
}

Field	Description
data	The array of requested JSON resource objects.
pagination.current_page	The current page number being returned.
pagination.per_page	The maximum requested number of items per page.
pagination.total_records	The total aggregate count of the items across all pages.
pagination.total_pages	Total pages available based on the total records and limit.
pagination.has_next	Boolean helper indicating if the client should request ?page=2.
pagination.has_previous	Boolean helper indicating if there is a previous page.

If invalid bounds are provided (e.g. ?page=-1 or ?page=9999), the API will return a standard 400 Bad Request or 404 Not Found following the Global Error Response format.