Errors and limits

Understand pagination, nearby search limits, status codes, and error response bodies.

This page covers the predictable behavior clients should rely on.

Pagination

Restaurant list responses include pagination metadata:

type PaginationMeta = {
  page: number;
  limit: number;
  total: number;
  totalPages: number;
};

Defaults and limits:

Value	Limit
Default page	`1`
Default list limit	`20`
Maximum list limit	`100`

Nearby search limits

Value	Limit
Default radius	`5000` meters
Maximum radius	`50000` meters
Default result limit	`20`
Maximum result limit	`100`

Invalid coordinates return a validation error.

Error body

Errors use this shape:

type ApiErrorBody = {
  error: string;
  code: string;
};

Example:

{
  "error": "Store not found",
  "code": "NOT_FOUND"
}

Common status codes

Status	Meaning
`400`	Validation error
`401`	Missing or invalid API key
`403`	API key does not have access
`404`	Resource not found
`409`	Duplicate or conflicting submission
`500`	Unexpected server error

SDK errors

The SDK converts failed responses into HalalEatsError:

try {
  await client.stores.get("missing-id");
} catch (error) {
  if (error instanceof HalalEatsError) {
    console.log(error.status);
    console.log(error.code);
    console.log(error.body);
  }
}

Caching

Public read endpoints may send cache headers. Clients should still handle stale or unavailable data gracefully.