Error Handling

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:

Kombo responds with validation error

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"
  }
}

Integration responds with categorized error

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")

Integration system is unavailable

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

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.

Is the `code` always present?

Not every error is categorized yet. So the code can also be null.

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.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.

Namespace `INTEGRATION`

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

`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.

General

Features

Guides

HRIS API Reference

General API Reference

DATEV

Error Handling

Error Format

Error Scenarios

FAQ

Which errors can be safely retried?

Is the `code` always present?

Error Codes

Namespace `PLATFORM`

`PLATFORM.RATE_LIMIT_EXCEEDED`

`PLATFORM.INPUT_INVALID`

`PLATFORM.UNKNOWN_ERROR`

Namespace `INTEGRATION`

`INTEGRATION.AUTHENTICATION_INVALID`

`INTEGRATION.QA_FAILED`

`INTEGRATION.SETUP_SYNC_PENDING`

`INTEGRATION.SETUP_INCOMPLETE`

`INTEGRATION.INACTIVE`

`INTEGRATION.MODEL_NOT_AVAILABLE`

`INTEGRATION.MODEL_DISABLED`

`INTEGRATION.ACTION_NOT_AVAILABLE`

`INTEGRATION.ACTION_DISABLED`

Namespace `REMOTE`

`REMOTE.SERVICE_UNAVAILABLE`

`REMOTE.RATE_LIMIT_EXCEEDED`

`REMOTE.INPUT_INVALID`

`REMOTE.UNKNOWN_HTTP_ERROR`

Namespace `ATS`

`ATS.JOB_CLOSED`

`ATS.APPLICATION_ALREADY_EXISTS`

General

Features

Guides

HRIS API Reference

General API Reference

DATEV

​Error Format

​Error Scenarios

​FAQ

​Which errors can be safely retried?

​Is the code always present?

​Error Codes

​Namespace PLATFORM

​PLATFORM.RATE_LIMIT_EXCEEDED

​PLATFORM.INPUT_INVALID

​PLATFORM.UNKNOWN_ERROR

​Namespace INTEGRATION

​INTEGRATION.AUTHENTICATION_INVALID

​INTEGRATION.QA_FAILED

​INTEGRATION.SETUP_SYNC_PENDING

​INTEGRATION.SETUP_INCOMPLETE

​INTEGRATION.INACTIVE

​INTEGRATION.MODEL_NOT_AVAILABLE

​INTEGRATION.MODEL_DISABLED

​INTEGRATION.ACTION_NOT_AVAILABLE

​INTEGRATION.ACTION_DISABLED

​Namespace REMOTE

​REMOTE.SERVICE_UNAVAILABLE

​REMOTE.RATE_LIMIT_EXCEEDED

​REMOTE.INPUT_INVALID

​REMOTE.UNKNOWN_HTTP_ERROR

​Namespace ATS

​ATS.JOB_CLOSED

​ATS.APPLICATION_ALREADY_EXISTS

Error Format

Error Scenarios

FAQ

Which errors can be safely retried?

Is the `code` always present?

Error Codes

Namespace `PLATFORM`

`PLATFORM.RATE_LIMIT_EXCEEDED`

`PLATFORM.INPUT_INVALID`

`PLATFORM.UNKNOWN_ERROR`

Namespace `INTEGRATION`

`INTEGRATION.AUTHENTICATION_INVALID`

`INTEGRATION.QA_FAILED`

`INTEGRATION.SETUP_SYNC_PENDING`

`INTEGRATION.SETUP_INCOMPLETE`

`INTEGRATION.INACTIVE`

`INTEGRATION.MODEL_NOT_AVAILABLE`

`INTEGRATION.MODEL_DISABLED`

`INTEGRATION.ACTION_NOT_AVAILABLE`

`INTEGRATION.ACTION_DISABLED`

Namespace `REMOTE`

`REMOTE.SERVICE_UNAVAILABLE`

`REMOTE.RATE_LIMIT_EXCEEDED`

`REMOTE.INPUT_INVALID`

`REMOTE.UNKNOWN_HTTP_ERROR`

Namespace `ATS`

`ATS.JOB_CLOSED`

`ATS.APPLICATION_ALREADY_EXISTS`