Docs
Errors
Errors are RFC 9457 problem details with Content-Type: application/problem+json. Failed requests (4xx and 5xx) never count toward your quota.
{
"type": "https://aistrail.com/docs/errors#window-too-large",
"title": "Window too large",
"status": 400,
"detail": "At raw resolution one query may span at most 24 hours; split the range or use a coarser resolution"
}Branch on the HTTP status and title; show detail to humans. Some errors add retry_after_s (seconds to wait; Rate limited, Too many concurrent requests and Server busy also send a Retry-After header) or upgrade_url (a link to the plans). The type is a link to the matching entry on this page, or about:blank.
Status codes and titles
400 Bad request
A parameter is missing or invalid, for example an area box larger than your plan allows or an IMO number where an MMSI is expected. The detail says which; fix the request and retry.
400 Window too large
The time range is longer than one query allows at this resolution (raw 24 h, 1m 7 days, 1h 366 days). Split the range or use a coarser resolution.
401 Unauthorized
The API key is missing or invalid. Send it as Authorization: Bearer ap_live_…
403 Plan limit
Your plan does not include this feature: area queries on Free, or real-time data, which is in early access and not part of any plan yet.
403 History limit
The requested range starts earlier than your plan's history depth (Free: last 7 days).
404 Not found
The vessel or endpoint does not exist in the sources available to your plan.
405 Method not allowed
Data endpoints accept only GET.
413 Payload too large
The request body is too large.
429 Rate limited
Too many requests per second for your key's plan, or more than 5 per second from one IP address without a valid key. Wait for Retry-After seconds and retry.
429 Too many connections
Too many open WebSocket connections for this key (real-time stream, early access only).
429 Too many concurrent requests
At most 2 requests per key are processed at a time. Wait for a response before sending the next request.
429 Quota exceeded
Your account's monthly request quota is used up. It resets at X-RateLimit-Reset (Unix time), the start of the next month in UTC.
500 Internal error
Something failed on our side. It has been logged; retry later or contact us at hello@aistrail.com.
503 Query timeout
The query took longer than the server limit and was stopped; it is not billed. Narrow the bounding box or time range, or use a coarser resolution.
503 Server busy
The server is under memory pressure; the request is not billed. Retry after Retry-After seconds.
Plain-text errors
Requests the HTTP server cannot parse (malformed, or with oversized headers or body) get a plain-text 400, 413 or 431 response instead of problem details.
Found a mistake, or something unclear? Suggest an edit and we will fix the page.
