​
Error Format

{
  "status": "error",
  "error": {
    "code": "INTEGRATION.MODEL_NOT_AVAILABLE",

    "title": "This data model isn't supported for the selected integration.",
    "message": "The \"employees\" model is not yet available for Greenhouse. Please reach out to Kombo if you need this functionality.",

    "log_url": "https://app.kombo.dev/my-prod/logs?interactionId=123456"
  }
}
  • code (nullable) - A unique identifier for programmatic error handling, used to determine the specific type of error that occurred. See the list below for all available codes.
  • title (nullable) - A static, human-readable label. (Note: While we initially only used the message field, we are gradually moving static error descriptions to the title field).
  • message - A dynamic, detailed description of what went wrong in this specific instance.
  • log_url (nullable) - A link to the log page in the dashboard where you can investigate the issue yourself. If you need assistance, please share this link with our support team.
When building error handling logic, always use the code field to identify specific error types programmatically. See the complete list of error codes below.Important: Do not write conditional logic based on the message field, as message text may change between releases. Similarly, avoid relying on HTTP status codes or other response properties, as these may be updated for consistency across the API.

​
Error Scenarios

The examples below demonstrate different error situations that can occur when using the Kombo API:
Scenario: You submit a request with missing fields. Kombo validates inputs and rejects the request with a platform validation error.
await fetch('https://api.kombo.dev/v1/ats/candidates', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <API_KEY>',
    'Content-Type': 'application/json',
    'X-Integration-Id': '<INTEGRATION_ID>',
  },
  body: JSON.stringify({
    // the body content is missing
  })
})

{
  "status": "error",
  "error": {
    "code": "PLATFORM.INPUT_INVALID",
    "title": "Your request contains invalid data and failed validation.",
    "message": "candidate: Required; application: Required",
    "log_url": "https://app.kombo.dev/my-prod/logs?interactionId=123456"
  }
}
Scenario: You’re building a job board that automatically applies candidates to positions. A candidate clicks “Apply” on a job they’ve already applied to previously.When you call POST /ats/applications to create the application, the ATS system (like Greenhouse) rejects it because the candidate already applied. However, Kombo categorizes this specific rejection with a structured error code:
{
  "status": "error",
  "error": {
    "code": "ATS.APPLICATION_ALREADY_EXISTS",
    "title": "Candidate has already applied to this job.",
    "message": "John Doe (john@example.com) has an existing application for Software Engineer position",
    // ...
  }
}
Error Handling: You can check for this specific error code and handle it appropriately:
// ...call to create application...

const body = await response.json()
if (body.error.code === "ATS.APPLICATION_ALREADY_EXISTS") {
  showInfo("You've already applied to this position.")
  return
}

throw new Error("Application failed")
Scenario: The downstream ATS/HRIS API experiences downtime or maintenance. After internal retries, Kombo returns a categorized remote error.
{
  "status": "error",
  "error": {
    "code": "REMOTE.SERVICE_UNAVAILABLE",
    "title": "The remote system is currently unavailable.",
    "message": "The API of \"Workday\" is currently unavailable. Please try again later.",
    "log_url": "https://app.kombo.dev/my-prod/logs?interactionId=123456"
  }
}
Error Handling: Implement retry with exponential backoff, or inform the user to try again later.

​
FAQ

​
Why the title and message?

Let’s imagine you get these two error responses: 
{
  "status": "error",
  "error": {
    "code": "REMOTE.INPUT_INVALID",
    "title": "The remote system returned validation errors.",
    "message": "Employee field 'department' is required for BambooHR",
    "log_url": null
  }
}

{
  "status": "error",
  "error": {
    "code": "REMOTE.INPUT_INVALID",
    "title": "The remote system returned validation errors.",
    "message": "Candidate field 'email' must be a valid email address for Greenhouse",
    "log_url": null
  }
}
They both have the code “REMOTE.INPUT_INVALID” and the same title of “The remote system returned validation errors.” However, while the title is always identical for this error code, the message varies completely depending on the integration. Each integration may format errors differently, and we don’t guarantee any specific message format or structure. (Note: Below in the list of error codes, you can see the current title text for each error type.)

​
Is the code always present?

Not every error is categorized yet. So the code can also be null. If the code is currently null but a specific error type (like ATS.JOB_CLOSED) would make sense, please contact support.

​
Which errors can be safely retried?

Requests failing with PLATFORM.RATE_LIMIT_EXCEEDED, REMOTE.RATE_LIMIT_EXCEEDED or REMOTE.SERVICE_UNAVAILABLE are generally safe to retry. If our load balancer responds with HTTP 503, you should retry the request as well. Validation errors (PLATFORM.INPUT_INVALID and REMOTE.INPUT_INVALID) can be retried after you correct the underlying input. For other errors, avoid automatic retries without human input. Use exponential backoff (preferably with jitter) for retries.

​
Error Codes

Some errors include an error code that can be used to identify their cause and write application logic to handle them appropriately. Since new error codes may be added in the future, your application logic should handle unknown error codes gracefully. Below, you can find a list of all the error codes that can be returned by the API:
Some error codes appear in pairs with different namespaces to indicate their origin:
  • PLATFORM.RATE_LIMIT_EXCEEDED and REMOTE.RATE_LIMIT_EXCEEDED
  • PLATFORM.INPUT_INVALID and REMOTE.INPUT_INVALID
  • PLATFORM.UNKNOWN_ERROR and REMOTE.UNKNOWN_HTTP_ERROR
PLATFORM errors come from Kombo while REMOTE errors (originally) come from the ATS/HRIS system.
We’re still finalizing our error categorization. Platform errors are already well-categorization, but not every remote-system error is fully classified yet. If you notice a missing or miscategorized error, please let us know.

​
Namespace PLATFORM

All the errors related to the general Kombo platform.

​
PLATFORM.RATE_LIMIT_EXCEEDED

Status Code: 429
Title: “Rate limit exceeded.”

​
PLATFORM.INTEGRATION_NOT_FOUND

Status Code: 404
Title: “Integration not found.”

​
PLATFORM.INPUT_INVALID

Status Code: 400
Title: “Your request contains invalid data and failed validation.”
Review the information that is being sent in the request, as there might be missing or invalid fields. Check the Logs for more details.

​
PLATFORM.UNKNOWN_ERROR

Status Code: 500
Title: “An unknown error occurred in our system.”
This is the fallback error message, when an unexpected error has occurred on the side of Kombo.We’re still improving our error categorization. If this seems like it should be a more specific error type (like ATS.JOB_CLOSED), please contact support.

​
PLATFORM.IP_NOT_WHITELISTED

Status Code: 403
Title: “Your IP address is not whitelisted.”

​
PLATFORM.AUTHENTICATION_INVALID

Status Code: 401
Title: “The provided authentication is invalid.”

​
Namespace INTEGRATION

All the errors related to the connection to a specific remote system.

​
INTEGRATION.PERMISSION_MISSING

Status Code: 400
Title: “A permission is missing in the remote system.”
Check in the Kombo dashboard which permissions are missing. Review the connection guide for how to add them and inform your customer of the required steps. For some integrations, a re-connect may be necessary.

​
INTEGRATION.AUTHENTICATION_INVALID

Status Code: 403
Title: “The integration cannot authenticate with the remote system.”
Use the reconnection link to re-authenticate the integration. If this repeats, review the logs and contact Kombo support.

​
INTEGRATION.QA_FAILED

Status Code: 503
Title: “The integration’s setup sync failed quality checks.”
No action is required on your side. Kombo support is investigating. We will notify you if any input or changes are needed from your side.

​
INTEGRATION.SETUP_SYNC_PENDING

Status Code: 503
Title: “The integration’s setup sync is still running.”
To prevent incomplete or inconsistent data, API requests are blocked until the setup sync completes.For larger remote systems, the initial sync can take longer. Monitor progress in the Kombo dashboard.If it takes unusually long or appears stuck, contact Kombo support. We can review the job and, if appropriate, trigger a limited “recent data only” sync to speed up availability.

​
INTEGRATION.SETUP_INCOMPLETE

Status Code: 503
Title: “The integration setup process is incomplete.”

​
INTEGRATION.INACTIVE

Status Code: 403
Title: “This integration is currently deactivated.”
In the Kombo Dashboard you can reactivate the integration.

​
INTEGRATION.MODEL_NOT_AVAILABLE

Status Code: 400
Title: “This data model isn’t supported for the selected integration.”
Look at the “Coverage Grid” in the Kombo Dashboard for more details. Reach out to the Kombo support if you need this functionality.

​
INTEGRATION.MODEL_DISABLED

Status Code: 403
Title: “This data model is disabled in the integration’s scope configuration.”
Go to the integration in the Kombo Dashboard. In the settings the “Scope config” is configured. Change this scope config to enable the functionality.

​
INTEGRATION.ACTION_NOT_AVAILABLE

Status Code: 400
Title: “This action isn’t supported for the selected integration.”
Look at the “Coverage Grid” in the Kombo Dashboard for more details. Reach out to the Kombo support if you need this functionality.

​
INTEGRATION.ACTION_DISABLED

Status Code: 400
Title: “This action is disabled in the integration’s scope configuration.”
Go to the integration in the Kombo Dashboard. In the settings the “Scope config” is configured. Change this scope config to enable the functionality.

​
Namespace REMOTE

All the errors originating from third-party HRIS/ATS systems.

​
REMOTE.SERVICE_UNAVAILABLE

Status Code: 500
Title: “The remote system is currently unavailable.”
This is usually due to scheduled maintenance or an outage on the vendor side. Check the logs for details. If it does not resolve within a few hours, please reach out to support.

​
REMOTE.RATE_LIMIT_EXCEEDED

Status Code: 429
Title: “Kombo has hit the rate limit of the integration’s API. Please try again later.”
Kombo is already retrying requests to the remote system automatically. Only when the backoff exceeds what we can do in the request we abort and return this error.

​
REMOTE.INPUT_INVALID

Status Code: 400
Title: “The remote system returned validation errors.”

​
REMOTE.UNKNOWN_HTTP_ERROR

Status Code: 400
Title: “The remote system returned errors.”
We’re still improving our error categorization. If this seems like it should be a more specific error type (like ATS.JOB_CLOSED), please contact support.

​
Namespace ATS

All the errors related to the ATS use-case.

​
ATS.JOB_CLOSED

Status Code: 400
Title: “The requested job is closed.”
This occurs when candidates try to apply to jobs that have been closed or archived in the ATS system. This is normal and not critical unless it happens frequently, which may indicate outdated job listings.
Ensure your UI filters out closed jobs and refreshes job statuses regularly. When this error occurs, show the user that the job is closed.

​
ATS.APPLICATION_ALREADY_EXISTS

Status Code: 400
Title: “The candidate has already applied to this job.”
Show the candidate that they have already applied to the job. If your system created the first application, restrict the candidate from applying again.