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 — Scale plan required

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

Organization API keys and unmanaged OAuth REST requests require an active Scale subscription. Grain-managed OAuth apps with an active grant can call /api/v1 on Starter and Growth. MCP access is available on Growth and Scale.

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.

403 — OAuth app reconnection required

{
  "message": "Reconnect this application and complete two-factor authentication."
}

Start a new Grain OAuth authorization-code flow. This can occur when an MFA-enrolled user authorized the app before the grant recorded MFA assurance. Grain also requires reconnection if the verified phone factor is removed after authorization.

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