Build with the API

Errors

The one error shape every failure uses, and the status codes you will meet.

When something goes wrong, every endpoint answers in the same shape, so you only have to write the error handling once.

An error

{
  "statusCode": 402,
  "message": "Your free plan allows 10 files per billing period and you have uploaded 10. The quota resets on 2026-11-01. Upgrade with PATCH /subscriptions/me to upload more now.",
  "correlationId": "7d2f6c0e-9e1a-4a35-8c7e-0b9d4b0f5a11",
  "timestamp": "2026-10-02T09:14:03.221Z"
}

statusCodenumberoptional: The HTTP status, repeated in the body.
messagestring | string[]optional: What went wrong, in plain words, and usually how to fix it. A request with several mistakes gets a list.
correlationIdstringoptional: An id for this request. It is on every log line the request produced, so quoting it lets support find exactly what happened.
timestampISO date-timeoptional: When it happened.

Status codes

Code	Name	Usually means
`400`	Bad Request	Something you sent is wrong: a missing field, a value out of range, an unknown field, a file that is not a spreadsheet. `message` lists each problem.
`401`	Unauthorized	No token, or one that is expired, revoked or invalid. See Authentication.
`402`	Payment Required	You are over a plan limit that stops work (the file quota on Free or Basic), or the company has not chosen a plan yet.
`403`	Forbidden	You are known but not allowed: your role is too low, your key lacks a scope, the company is suspended, or it is the read-only demo.
`404`	Not Found	It does not exist or you may not see it. Gridline never tells you which.
`409`	Conflict	The request is fine but clashes with the current state: a plan limit on people, rules or versions; a report already being built; an address that is already registered.
`413`	Payload Too Large	A file over 25 MB, or an AI-agent upload over its limit.
`422`	Unprocessable	Understood but impossible: comparing files that are not versions of each other, or reusing an Idempotency-Key for a different request.
`429`	Too Many Requests	Your company has used its request budget for this minute. See Rate limits.
`500`	Server Error	Our fault, not yours. The message is generic on purpose; quote the `correlationId`.

Handling errors well

Show `message` to a person. It is written to be read, and it usually says the next step.
Do not retry a `4xx` unchanged: it will fail the same way. The exceptions are 409 while something finishes, and 429 after waiting.
Retry `5xx` and network errors with a growing delay, and use an Idempotency-Key on anything that creates something.
Log the `correlationId`. It is the fastest way to a fix.