--- title: "API Error Codes" description: "Complete reference of API error codes and how to resolve them" url: "https://developer.yukisoftware.com/guides/error-codes" image: "https://developer.yukisoftware.com/_og/d/c_Ocean.takumi,title_API+Error+Codes,description_Complete+reference+of+API+error+codes+and+how+to+resolve+them,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiNGM0EyMUMifX19,p_Ii9ndWlkZXMvZXJyb3ItY29kZXMi,s_MikvSDS1zTWFDiGI.png" --- ## API Error Codes A complete reference for all error codes returned by the Yuki API. Use this guide to understand what went wrong and how to resolve it quickly. ## [Error Response Format](#error-response-format) All errors returned by the Yuki API follow [RFC 7807 – Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc7807). Understanding this structure helps you handle errors programmatically. ```json { "type": "https://httpstatuses.com/422", "title": "Validation Error", "status": 422, "errors": { "validation:invalid_input": [ "The email field is not a valid email address." ] }, "traceId": "00-ad89db24d04645ed383f4b90c1913602-0b19ca914794928b-00", "errorCode": "validation:invalid_input" } ``` | Field | Type | Description | | :-------- | :------ | :------------------------------------------------------------------------------- | | type | string | A URI that identifies the error type. Points to the relevant HTTP status documentation. | | title | string | A short, human-readable summary of the error type. | | status | integer | The HTTP status code for this error. | | errors | object | A map of error codes to arrays of descriptive messages. There may be more than one entry when multiple validations fail. | | traceId | string | A W3C Trace Context identifier for the request. Always include this when contacting support. | | errorCode | string | The primary error code, matching the key in errors. Use this for programmatic error handling. | ## [HTTP Status Codes](#http-status-codes) The Yuki API uses standard HTTP status codes to indicate the outcome of each request. | HTTP Status | Meaning | When it occurs | | :------------------------ | :--------------------- | :----------------------------------------------------------------------------- | | 200 OK | Success | The request was processed successfully and a response body is returned. | | 201 Created | Resource created | A new resource was successfully created. | | 204 No Content | Success, no body | The request succeeded but there is no response body (e.g. DELETE). | | 400 Bad Request | Invalid request | The request is malformed, missing required fields, or contains invalid values. | | 401 Unauthorized | Authentication failure | The access token is missing, expired, or invalid. | | 403 Forbidden | Authorization failure | The authenticated user does not have permission to perform this action. | | 404 Not Found | Resource not found | The requested resource does not exist. | | 409 Conflict | State conflict | The request conflicts with the current state of the resource. | | 422 Unprocessable Entity | Validation error | The request body is syntactically correct but semantically invalid. | | 429 Too Many Requests | Rate limit exceeded | The client has sent too many requests in a given time window. | | 500 Internal Server Error | Server error | An unexpected condition occurred on the server side. | | 503 Service Unavailable | Service down | The API is temporarily unavailable. Retry after a short delay. | ## [Error Code Reference](#error-code-reference) The following tables list all error codes grouped by category. --- ### [Authentication](#authentication) | Error Code | HTTP Status | Description | Resolution | | :-------------------------- | :---------- | :------------------------------------------------------------------------------- | :------------------------------------------------------------------------------- | | authentication:unauthorized | 401 | The request is missing a valid access token, or the token is invalid or expired. | Include a valid Authorization: Bearer header. Re-authenticate via Visma Connect to obtain a fresh token. | | authentication:forbidden | 403 | The authenticated user does not have permission to perform this action. | Verify that your application and user have been granted access to the requested resource in Yuki. | --- ### [Validation](#validation) | Error Code | HTTP Status | Description | Resolution | | :-------------------------------- | :---------- | :----------------------------------------------------------- | :------------------------------------------------------------------------------- | | validation:invalid_input | 422 | The request contains one or more fields with invalid values. | Check the errors map for field-level messages that describe what is wrong with each value. | | validation:missing_required_field | 400 | A required field is absent from the request body. | Ensure all required fields are included in your request payload. | --- ### [Companies](#companies) | Error Code | HTTP Status | Description | Resolution | | :-------------------------- | :---------- | :------------------------------------------------------------------------- | :------------------------------------------------------------------------------- | | companies:not_found | 404 | The specified company (administration) does not exist. | Verify the administration ID and that it is accessible by your application. | | companies:validation_failed | 422 | The request to create or modify a company failed validation. | Check the errors map for details on which fields are invalid. | | companies:update_failed | 409 | The company could not be updated due to a conflict with its current state. | Retrieve the current state of the company and retry the operation with valid data. | --- ### [Domains](#domains) | Error Code | HTTP Status | Description | Resolution | | :------------------------ | :---------- | :------------------------------------------------------------------------ | :------------------------------------------------------------------------------- | | domains:not_found | 404 | The specified domain does not exist. | Verify the domain identifier and that it belongs to the correct administration. | | domains:validation_failed | 422 | The domain request failed one or more validation rules. | Check the errors map for field-level validation messages. | | domains:creation_failed | 422 | The domain could not be created. | Review the request payload and ensure it meets all domain creation requirements. | | domains:update_failed | 409 | The domain could not be updated due to a conflict with its current state. | Retrieve the current state of the domain and retry the operation with valid data. | --- ### [Portals](#portals) | Error Code | HTTP Status | Description | Resolution | | :------------------------ | :---------- | :------------------------------------------------------ | :-------------------------------------------------------------------------- | | portals:not_found | 404 | The specified portal does not exist. | Verify the portal identifier and that it is accessible by your application. | | portals:validation_failed | 422 | The portal request failed one or more validation rules. | Check the errors map for details on which fields are invalid. | --- ### [Rate Limiting](#rate-limiting) Rate limiting is enforced at the API gateway level and returns HTTP `429 Too Many Requests`. These responses do not include an application-level `errorCode` field. Check the `Retry-After` response header for the number of seconds to wait before retrying. If you are consistently hitting rate limits, contact [Yuki Support](https://www.yukisoftware.com/nl-nl/support/) to review your quota. --- ### [Server Errors](#server-errors) | Error Code | HTTP Status | Description | Resolution | | :---------------------- | :---------- | :----------------------------------------------------------------------- | :------------------------------------------------------------------------------- | | server:internal_error | 500 | A known internal error occurred on the server. | This is not related to your request. Retry after a short delay. If the issue persists, contact Yuki Support and provide the traceId from the error response. | | server:unexpected_error | 500 | An unhandled exception occurred that does not map to a known error type. | Retry after a short delay. If the issue persists, contact Yuki Support and provide the traceId. | ## [Handling Errors in Your Application](#handling-errors-in-your-application) Follow these best practices to handle API errors gracefully in your integration. ### [Check the HTTP status code first](#check-the-http-status-code-first) Use the HTTP status code as the primary signal to branch your error handling logic before inspecting the `code` field. ```javascript const response = await fetch('https://api.yukisoftware.com/v1/administrations', { headers: { Authorization: `Bearer ${accessToken}` } }); if (!response.ok) { const body = await response.json(); console.error(`[${body.errorCode}] ${body.title} (traceId: ${body.traceId})`); switch (body.errorCode) { case 'authentication:unauthorized': // Token missing, invalid or expired — redirect to login and re-authenticate break; case 'authentication:forbidden': // User lacks permission — show access denied message break; case 'validation:invalid_input': case 'validation:missing_required_field': // Surface the per-field messages to the user console.error(body.errors); break; case 'companies:not_found': case 'domains:not_found': case 'portals:not_found': // Resource does not exist — handle gracefully break; default: // Generic fallback — log traceId for support console.error('traceId:', body.traceId); break; } } ``` ### [Implement retry logic with back-off](#implement-retry-logic-with-back-off) For transient errors (`429`, `503`, `502`), retry the request with exponential back-off. ```javascript async function fetchWithRetry(url, options, maxRetries = 3) { for (let attempt = 0; attempt < maxRetries; attempt++) { const response = await fetch(url, options); if (response.status !== 429 && response.status !== 503) { return response; } // Wait before retrying: 1s, 2s, 4s ... const delay = Math.pow(2, attempt) * 1000; await new Promise(resolve => setTimeout(resolve, delay)); } throw new Error('Max retries reached'); } ``` ### [Log the traceId](#log-the-traceid) Always log the `traceId` from error responses. Should you need to contact support, providing this value allows Yuki's team to investigate the exact request in question. ## [Need Help?](#need-help) If you encounter an error not listed here, or if you believe a server error is impacting your integration, reach out to the Yuki support team. - **Support portal:** [yukisoftware.com/support](https://www.yukisoftware.com/nl-nl/support/) - **Include in your report:** the `traceId`, the endpoint called, the request payload (redacted of sensitive data), and the timestamp of the error.