Troubleshooting

baseUrl is required

The SDK intentionally has no default deployment. Set OKATANA_URL or call .baseUrl(...) with your actual Okatana instance.

401

Check token completeness, expiry, revocation, and the deployment URL. Do not retry unchanged credentials automatically.

403

Check credential organization and scope. A credential cannot cross organization boundaries even with *.

404

Confirm that the ID exists and has not been soft-deleted, and that relationship-constrained identifiers belong to the expected project/organization.

422

Inspect OkatanaValidationException.errors() and getMessage(). Common server-side causes include invalid relationships, WIP limits, duplicate project keys, or lifecycle rules.

429

Reduce request pressure and inspect retryAfter(). GET operations can retry automatically with jitter.

Paginator URL rejected

The server returned a navigation URL outside the configured API scheme/host/port/path. Check reverse-proxy base URL generation. Do not disable the SDK check by forwarding the bearer token manually.

Empty dynamic field

The field may not be returned by that deployment/version. The OpenAPI file does not define fixed schemas for several dynamic endpoints. Inspect resource.extra().

PATCH did not clear a nullable field

Call the setter with null. Not calling the setter means omit the field.