Troubleshooting¶
OkatanaConfigurationException: BaseUrl is required¶
The SDK has no default deployment. Configure the actual Okatana instance URL. Do not use the public documentation host as an assumed API server.
Requests are going to the wrong path¶
Inspect client.BaseApiUri. A root such as https://host.example/okatana normalizes to https://host.example/okatana/api/v1/. If you supply a URL that already ends in /api/v1, the SDK does not append it again.
401 Unauthorized¶
Check that the bearer credential is complete, active, not revoked, and not expired. Confirm you did not provide only the public credential identifier.
403 Forbidden¶
The credential is valid but either lacks the required scope or does not belong to the organization that owns the target resource. Check the scope map and the resource organization.
404 Not Found¶
The route-bound object can be missing or soft-deleted. Relationship-constrained IDs can also fail if they do not belong to the expected project/organization. Refresh IDs through list endpoints.
422 Unprocessable Entity¶
Inspect OkatanaValidationException.Errors and Message. Field-level validation usually includes an errors dictionary. Business rules can return only a message. Common causes include WIP limits, cross-project board/label IDs, invalid members/editors, lifecycle rules, and duplicate project keys.
429 Too Many Requests¶
Inspect OkatanaRateLimitException.RetryAfter. Safe GET operations can retry automatically. Writes should not be blindly retried because the API has no idempotency key.
Pagination throws OkatanaUnexpectedResponseException¶
The server returned an absolute next_page_url that does not match the configured scheme/host/port or escaped the configured API base path. This check is intentional to prevent bearer-token leakage. Confirm reverse-proxy URL generation and the configured deployment URL.
A PATCH did not clear a nullable field¶
Assign the property explicitly to null:
Leaving the property out means "do not change it".
A write was duplicated after a timeout¶
The current API has no idempotency-key mechanism. Reconcile the resource using a stable marker or stored ULID before repeating a create. See Retries and idempotency and External tracker synchronization.
Custom HttpClient times out earlier than the SDK¶
The caller-managed HttpClient.Timeout can still cancel a request. Set it to Timeout.InfiniteTimeSpan or a value at least as large as the SDK timeout when you want OkatanaClientOptions.Timeout to be authoritative.