Requests, paging & errors

The Gurita API speaks JSON, pages its list endpoints with a common set of query parameters, and returns every error in the same envelope.

Requests

• Send and expect JSON: Content-Type: application/json and Accept: application/json.
• Dates are ISO 8601 strings, e.g. 2026-12-24T00:00:00.000Z.
• Authenticate every request with your API key.

Paging

Paged list endpoints — for example GET /api/customers — accept these query parameters:

Parameter	Default	Meaning
page	1	Page number, starting at 1.
size	10	Items per page. Maximum 1000; 0 returns everything.
sort	—	Field to sort by.
order	-1	1 ascending, -1 descending.
filter	—	JSON filter object, e.g. {"status":"active"}. URL-encode it.
search	—	Free-text search.
select	—	Comma-separated list of fields to return.
populate	—	Related records to include.

curl -H "Authorization: UserKey <userId>.guk_…" \
  "https://YOUR-DOMAIN/api/customers?page=2&size=20&order=-1"

The response wraps the results with the paging totals:

{
  "data": [ { "_id": "…" }, { "_id": "…" } ],
  "count": 123,
  "pages": 13,
  "page": 2,
  "size": 10
}

Field	Meaning
data	The records on this page.
count	Total number of matching records.
pages	Total number of pages.
page	The page returned.
size	Items per page.

Errors

Every error has the same shape, whatever the status code:

{
  "status": "ERROR",
  "statusCode": 401,
  "error": "UnauthorizedException",
  "message": "USER_KEY_INVALID",
  "description": "Translated user-friendly description",
  "timestamp": "2026-09-22T12:34:56.000Z",
  "path": "/api/customers",
  "method": "GET"
}

Field	Meaning
status	Always "ERROR".
statusCode	The HTTP status code.
error	The error type.
message	An error code such as USER_KEY_INVALID, or validation details — a string, a list of strings or an object keyed by field.
description	A human-readable explanation, when one exists.
timestamp, path, method	When and where the error happened.

Branch on statusCode and message in your code; show description to people.

Status	Typical cause
400	Invalid input — check message for the field.
401	Missing, invalid, revoked or expired API key.
403	The user lacks permission, or the route doesn't accept API keys.
404	The record doesn't exist or isn't visible to this user.
409	Conflict, e.g. a limit is reached.
5xx	Server error — retry later; contact Gurita if it persists.

Money

Amounts come with their currency:

{ "price": 150.0, "currency": "EUR" }

price is in the major unit (euros, not cents). currency is an ISO 4217 code.

Stability

The API is the same one the Gurita app uses. It isn't versioned yet, and there is no public endpoint reference, so routes and fields can change between releases. Planning an integration? Contact us and we'll point you to the right endpoints.

Related

• Authentication & API keys