- Send one Authorization: Bearer credential. It defines App, environment, audience and permissions.
- Optional scope headers must appear together and match the credential. POST bodies use application/json. Default body limit: 16 KiB; customer write bodies, including attributes, are limited to 32 KiB.
- Standard customer and commerce API responses carry requestId and scope. Errors use { requestId, error: { code, message } }; X-Request-Id aids troubleshooting. Responses are no-store.
- The SDK does not follow redirects or retry automatically. It uses a 10-second timeout including response-body reading. Reuse stable requestId, eventId or idempotencyKey for a write retry.
| HTTP | Code | Meaning |
|---|---|---|
| 400 | INVALID_REQUEST | The request body or parameters do not match the contract. |
| 401 | UNAUTHENTICATED | The credential is missing, invalid, expired or revoked. |
| 403 | FORBIDDEN | The credential lacks permission or the browser origin is not allowed. |
| 403 | SCOPE_MISMATCH | The scope headers do not match the credential’s App and environment. |
| 404 | NOT_FOUND | The object does not exist in the current App and environment. |
| 409 | CONFLICT | The request conflicts with existing data, for example different content under the same eventId. |
| 413 | PAYLOAD_TOO_LARGE | The request exceeds the endpoint’s body-size limit. |
| 429 | RATE_LIMITED | The request rate exceeds the limit; retry later. |
| 500 | INTERNAL_ERROR | An internal failure or invalid response occurred. Internal exception details are not exposed. |
| 501 | NOT_CONFIGURED | The capability is not configured or has not been implemented. |
| 503 | SERVICE_UNAVAILABLE | The service is temporarily unavailable; retry later. |
HTTP errors
INVALID_REQUEST400- Meaning
- The request body or parameters do not match the contract.
UNAUTHENTICATED401- Meaning
- The credential is missing, invalid, expired or revoked.
FORBIDDEN403- Meaning
- The credential lacks permission or the browser origin is not allowed.
SCOPE_MISMATCH403- Meaning
- The scope headers do not match the credential’s App and environment.
NOT_FOUND404- Meaning
- The object does not exist in the current App and environment.
CONFLICT409- Meaning
- The request conflicts with existing data, for example different content under the same eventId.
PAYLOAD_TOO_LARGE413- Meaning
- The request exceeds the endpoint’s body-size limit.
RATE_LIMITED429- Meaning
- The request rate exceeds the limit; retry later.
INTERNAL_ERROR500- Meaning
- An internal failure or invalid response occurred. Internal exception details are not exposed.
NOT_CONFIGURED501- Meaning
- The capability is not configured or has not been implemented.
SERVICE_UNAVAILABLE503- Meaning
- The service is temporarily unavailable; retry later.
| Code | Meaning |
|---|---|
NOT_IDENTIFIED | Call identify with a customer token before requesting customer data. |
INVALID_TOKEN | The token is empty or a server key was supplied to the browser client. |
SERVER_ONLY | The server client was constructed in a browser. |
TIMEOUT | The request timed out (10 seconds by default; configurable from 1–120,000 ms). |
NETWORK_ERROR | The network request failed. The SDK does not retry automatically. |
IDENTITY_CHANGED | The identity changed or reset was called during the request; the old response was discarded. |
SCOPE_MISMATCH | The response’s App or environment does not match the configured scope. |
INVALID_REQUEST | Local validation rejected the method parameters. |
INVALID_RESPONSE | The server response does not match the contract. |
HTTP_ERROR | The server returned an error response that could not be parsed. |
INVALID_URL | baseUrl must use HTTPS (localhost HTTP is allowed) and contain no credentials or query parameters. |
INVALID_TIMEOUT | timeoutMs must be between 1 and 120,000 milliseconds. |
Client errors
NOT_IDENTIFIED- Meaning
- Call identify with a customer token before requesting customer data.
INVALID_TOKEN- Meaning
- The token is empty or a server key was supplied to the browser client.
SERVER_ONLY- Meaning
- The server client was constructed in a browser.
TIMEOUT- Meaning
- The request timed out (10 seconds by default; configurable from 1–120,000 ms).
NETWORK_ERROR- Meaning
- The network request failed. The SDK does not retry automatically.
IDENTITY_CHANGED- Meaning
- The identity changed or reset was called during the request; the old response was discarded.
SCOPE_MISMATCH- Meaning
- The response’s App or environment does not match the configured scope.
INVALID_REQUEST- Meaning
- Local validation rejected the method parameters.
INVALID_RESPONSE- Meaning
- The server response does not match the contract.
HTTP_ERROR- Meaning
- The server returned an error response that could not be parsed.
INVALID_URL- Meaning
- baseUrl must use HTTPS (localhost HTTP is allowed) and contain no credentials or query parameters.
INVALID_TIMEOUT- Meaning
- timeoutMs must be between 1 and 120,000 milliseconds.
Catch GrooveError and record code, status and requestId. Never record the server key or customer token. Refresh expired customer sessions through your own authenticated backend before retrying.