API referenceOpen the app

Reference

Troubleshooting

The errors people hit most often, what they mean and the fix.

Most problems have one of a few causes. Find what you are seeing below. Every error also carries a correlationId: if none of this helps, quote it when you ask for help.

My request was refused

You see	Likely cause	What to do
`401` "Invalid email or password"	Wrong password, or no account for that address.	Check both. Use Forgot your password? if needed. The message is the same for both on purpose.
`401` on every call	The token is missing, expired (15 minutes) or revoked.	Sign in again, or refresh the session. For a key: is it revoked, or was its owner removed?
`403` "not activated yet"	The activation link has not been used.	Open the link in the email, or ask for a new one: `POST /auth/resend-activation`.
`403` "lacks the required scope: files:write"	The API key was made without that scope.	Make a new key with the scope. Scopes cannot be added to an existing key.
`403` "API keys cannot be used with this endpoint"	That endpoint is closed to keys by design.	Use a signed-in session. See API keys.
`403` "read-only demo"	You are in the demo company.	Create your own company to make changes.
`403` suspended	A payment failed and the grace period ended.	An admin can sign in and pay in Billing. Access returns when it is paid.
`402` "No plan selected yet"	The company has not chosen a plan.	An admin chooses one: `POST /subscriptions/me`.
`402` about your plan allowing N files	You reached the file quota on Free or Basic.	Wait for the reset date in the message, or upgrade: `PATCH /subscriptions/me`.
`404` for something you know exists	You may not see it, or it belongs to another company.	Ask the uploader or an admin to share it. Gridline cannot tell you which.
`409` about plan limits	You hit a limit on people, rules, versions or webhook endpoints.	Remove one, or upgrade. See Limits.
`413`	The file is over 25 MB.	Split it, or export it as CSV.
`422` on an Idempotency-Key	The same key was used for a different request.	Make a new UUID for each distinct request.
`429`	The company used its requests for this minute.	Wait for `Retry-After`. See Rate limits.

My upload or report is not working

You see	Likely cause	What to do
`400` "Only CSV, XLS and XLSX spreadsheets are accepted"	The bytes are not a spreadsheet, whatever the name says. A CSV with unusual control characters can also trip this.	Re-export it as CSV or XLSX.
Report stays `queued`	The background worker has a backlog.	Wait a little, then check again. Transient problems retry automatically.
Report `failed`	The file itself is unreadable: corrupt, unclosed quote, or too large when expanded.	Read `errorMessage`. Fix the file and upload it as a new version.
Report `unsupported`	A legacy `.xls` file.	Save it as `.xlsx` or CSV to get a report.
`qualityScore` is `null`	No rule applied to this file.	Add rules, or check the column names they use (matching ignores case).
Preview or comparison answers `409`	A report is still being built.	Ask again in a moment.
A new version was refused with `409`	Your plan's limit on versions of one file.	Delete an old version or upgrade.

You see	Likely cause	What to do
No activation or reset email	It is in spam, or the address is wrong. The answer is the same either way.	Check spam, then ask again. Reset links work once and only the newest works.
"This invitation link is invalid"	It was used, replaced by a newer invitation, or expired.	Ask your admin to resend it.
Google says the sign-in expired	It started in a different browser, or took too long.	Start again from the sign-in page, in one browser.
Google sign-in did not join my account	Gridline links only when Google vouches for an address that matches one active person.	Sign in with your password, then connect Google from Settings → Linked accounts.
"An account with this email already exists"	One login email is one account.	Use a different address for the second company, or sign in.
My API key stopped working	It was revoked, its owner was removed or demoted, or it lacks a scope that an admin-only change removed.	Check Developers → API keys. Make a new key if needed.

Webhooks and live updates

You see	Likely cause	What to do
No webhooks arrive	The endpoint is disabled (20 failed deliveries, or a `410`), or it is subscribed to other events.	`GET /outgoing-webhooks` shows `active`. Fix the receiver and set `active: true`.
Signature check fails	You signed a parsed or changed body, or used an old secret.	Sign the raw body with the current `whsec_…` secret. See Webhooks.
The same event arrives twice	Delivery is at least once.	Skip repeats using the `webhook-id` header.
The live connection is refused	You sent an API key, or the token expired.	Connect with a fresh access token.