Errors

The Grain API uses standard HTTP status codes. Error responses include a JSON body with a message field describing what went wrong.

Error response format

{
  "message": "You do not have access to this organization."
}

Some validation errors may include additional fields depending on the endpoint.

Common status codes

Status	Meaning	Typical cause
`400`	Bad request	Missing OAuth `X-Organization-Id` header or invalid request body
`401`	Unauthorized	Missing/expired OAuth token or malformed, unknown, expired, or revoked API key
`403`	Forbidden	Missing API-key scope, user permission, matching organization access, or required plan
`404`	Not found	Resource ID does not exist in the organization
`409`	Conflict	Duplicate record (for example donor with same name and email)
`422`	Unprocessable entity	Validation failed on one or more fields
`429`	Too many requests	Rate limit exceeded
`500`	Server error	Unexpected error; retry with backoff

Authentication errors

401 — Authentication required

{
  "message": "Authentication required. Provide a valid Bearer token."
}

Refresh your OAuth access token, re-run OAuth, or rotate the organization API key. API-key failures use one generic response so callers cannot probe key state.

400 — Missing organization header

{
  "message": "X-Organization-Id header is required for all API requests."
}

Add the header to OAuth requests. It is optional for organization API keys. See Organizations.

403 — API key scope denied

A valid API key does not include the scope required by the endpoint. Create a replacement key with the needed scope; existing key scopes cannot be edited.

403 — Enterprise plan required

{
  "message": "REST API access is available on the Enterprise plan."
}

Organization API keys and REST API requests require an active Enterprise subscription. MCP access is available on Growth and Enterprise.

403 — Organization access denied

{
  "message": "You do not have access to this organization."
}

The authenticated user is not a member of the organization in X-Organization-Id.

Handling errors in your integration

Log the status code and message field for debugging. Do not log full Bearer tokens.

const response = await fetch(url, { headers });

if (!response.ok) {
  const error = await response.json().catch(() => ({}));
  throw new Error(`Grain API ${response.status}: ${error.message ?? response.statusText}`);
}

response = requests.get(url, headers=headers)

if not response.ok:
    error = response.json() if response.content else {}
    raise RuntimeError(
        f"Grain API {response.status_code}: {error.get('message', response.reason)}"
    )

Rate limiting

When you exceed the per-organization rate limit, the API returns 429 with rate limit headers. Wait until X-RateLimit-Reset before retrying. See Introduction for default limits.

Overview

Core concepts

Error response format

Common status codes

Authentication errors

Handling errors in your integration

Rate limiting

​Error response format

​Common status codes

​Authentication errors

​Handling errors in your integration

​Rate limiting

Error response format

Common status codes

Authentication errors

Handling errors in your integration

Rate limiting