Errors & status codes

Handle GraphQL and REST failures consistently.

HTTP status codes

Code	Meaning	Action
`400`	`Invalid request or validation failure`	`Fix fields, types, or path parameters.`
`401`	`Missing or invalid credentials`	`Check the credential and header format.`
`403`	`Wrong clientId, insufficient key scope, or admin-only operation`	`Discover the scoped client and confirm key permissions.`
`404`	`Resource not found for this client or partner`	`Confirm referenceId and ownership.`
`429`	`Rate limit reached`	`Back off and retry after the indicated window.`
`500`	`Unexpected server failure`	`Retry with jitter; contact support if persistent.`

GraphQL error shape

GraphQL may return HTTP 200 with an errors array. Always check errors before reading data. Production introspection is disabled, so use this reference as the schema discovery surface.

json

{"errors":[{"message":"Forbidden","extensions":{"code":"FORBIDDEN"}}],"data":null}

Troubleshooting

A 403 is usually scope, not authentication

First run getMyClients and use its id. Client keys are scoped to exactly one client, and some schema operations remain staff-only.