Troubleshooting

Incorrect host called

Verify Configuration::$baseUrl targets the deployment, not the documentation site. Print the normalized base URL in local debugging without printing the token.

401 Unauthorized

Verify the token is complete, current, and active. Do not retry 401 errors automatically.

403 Forbidden

Verify credential scope and organization boundaries. Credentials scoped to one organization cannot perform cross-organization administrative actions.

422 Validation

Catch ValidationException and inspect errors() and decoded(). Relationship and WIP rules may produce a message without field errors.

POST timeout

Do not immediately replay the write. The API may have committed the first request. Reconcile by looking for the created resource or another unique marker before deciding whether to retry.

Pagination returns single page

Read pagination()->lastPage, nextPageUrl, and hasNextPage(). If your deployment does not accept the SDK's compatibility page query parameter, use its actual documented pagination behavior and the low-level client as needed.

Custom PSR-18 client ignores SDK timeout

Expected. Configuration::$timeout configures only the default Guzzle transport. Configure timeouts on an injected transport according to that transport's own API.

Response has a new field

Use $response->data() or a model's $raw property. The SDK intentionally keeps unknown response properties.