This article covers the most common errors developers encounter when integrating with the Cinode REST API, and how to resolve them. For full endpoint documentation and authentication setup, see the REST API article.
Authentication errors
401 Unauthorized
The request was made without a valid token, or the token has expired.
Ensure you are including the Authorization header in every request.
Access tokens expire — use the refresh token endpoint (https://api.cinode.com/token/refresh) to obtain a new one without re-authenticating.
If you are using Basic Authentication, confirm that the credentials are Base64-encoded correctly.
Check that the API account has the required roles for the endpoint you are calling (see 'Role and permission errors' below).
403 Forbidden
Your token is valid but the API account does not have permission to perform the requested action.
Every API request runs in the context of the API account that owns the token. The account must have the appropriate role combination for the action.
For example, creating projects requires both the Business module and the Manager role.
Review the required roles for the endpoint in the API documentation and update the API account's roles accordingly in Administration → Users.
Validation errors (400 Bad Request)
A 400 response means the request body failed validation. The response body typically contains a list of field-level errors.
Required field missing
Read the error message carefully — it names the specific field that is missing or invalid.
Check the API documentation for the endpoint to confirm all required fields and their expected formats.
Null and empty string are treated differently for some fields — use null only where the docs indicate it is accepted.
Invalid ID — entity not found
This occurs when an ID you pass in the request body (for example, a skill ID, user ID, or company ID) does not exist in the system.
Use the corresponding GET endpoint to look up and confirm the ID before using it in a write request.
IDs are company-scoped — an ID valid in one Cinode company will not work in another.
If you are storing IDs from a previous API response, check that the entity has not been deleted since you last fetched it.
Enum or list value out of range
Enum fields (such as skill level, role type, or status) accept only specific integer values. Refer to the API documentation for the valid values for each field.
Passing a value outside the accepted range returns a validation error. Do not assume enum values — always check the docs.
Silent data issues (no error returned, but data looks wrong)
Some integration problems do not return an error — the request succeeds but the data in Cinode is incomplete or unexpected.
Data written via API does not appear in the UI
Confirm the write request returned a 200 or 201 status code and that the response body contains the expected data.
Check that the entity is linked to the correct user and company — a mismatch in company ID is a common cause.
Some fields (such as skills on a profile) require a visibility toggle to be enabled before they appear in CVs — the API write alone is not enough.
Duplicate entries created on repeated requests
The Cinode API does not deduplicate on most POST endpoints — calling the same endpoint twice with the same payload will create two entries.
Use GET first to check whether the entity already exists before creating it.
For skills specifically, skills are appended on every write — verify the current skill list before adding.
Webhook events not arriving
Check that the webhook endpoint URL is reachable from the internet and returns a 2xx response within the timeout window.
Cinode rejects endpoint URLs that point to loopback addresses or unresolvable hosts — use a publicly accessible URL.
Review the webhook configuration in Administration → Integrations and confirm the correct event types are subscribed.
Failed deliveries are not automatically retried — if your endpoint was temporarily down, you will need to re-fetch the missed data via the corresponding GET endpoint.
Rate limiting and performance
If you receive 429 Too Many Requests responses, your integration is exceeding the API rate limit.
Implement exponential backoff and retry logic in your integration.
Batch read operations using list endpoints rather than fetching individual records in a loop.
Contact Cinode Support if you have a legitimate use case that requires a higher rate limit.
Still stuck?
If you cannot resolve the issue using the steps above, contact Cinode Support with the following information to speed up the investigation:
The full API endpoint URL and HTTP method used.
The request body (with any sensitive credentials removed).
The full response body, including the HTTP status code.
The timestamp of the failing request (in UTC).
The Cinode company ID the API account belongs to.