> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bindbee.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Find the Source of an Error

> Differentiate a Bindbee failure from an origin-system one.

A model reports **Failed** on [sync status](/guides/troubleshooting/sync-status). Its **Issue** field names where the failure came from.

| Issue               | What happened                          | Who fixes it                      |
| ------------------- | -------------------------------------- | --------------------------------- |
| Integration Partner | The source system refused the request  | The customer's HRIS administrator |
| Bindbee             | The sync or mapping failed on our side | Bindbee                           |

The **Message** beside it carries the source system's response verbatim.

## Bindbee errors

Report the failure with the connector ID, the failing model, and the timestamp of the run. An error message on its own rarely locates it.

## Origin-system errors

The credentials the connector authenticated with are almost always the problem. An integration user provisioned below the permissions the sync needs is the case Bindbee sees most - a Workday ISU without its minimum grants, or API credentials scoped more narrowly than the models you enabled.

Bindbee reads what those credentials expose. Many HR systems answer a permission gap with an empty result rather than an error, so a gap can surface as missing data instead of a failure.

<Info>
  **Before you start**

  * You have the connector ID and the name of the affected model or field.
  * You can reach the customer's HRIS administrator.
</Info>

### Steps

<Steps>
  <Step title="Read the source system's own response">
    Open **Logs** for the connector and find the failing request. Bindbee keeps the source system's answer as it arrived: the upstream status, the endpoint called, and the response body. See [Logs](/guides/troubleshooting/logs).

    That body stays unnormalized on purpose. *"The Workday integration system user lacks Get\_Workers permission on this security group"* is the sentence an administrator can act on, and `PERMISSION_DENIED` would lose it.

    **Result:** You know which upstream resource was refused.
  </Step>

  <Step title="Name the access the failing model needs">
    Translate the model that failed into the access it needs.

    | Failing model or field                           | Access to grant                                                |
    | ------------------------------------------------ | -------------------------------------------------------------- |
    | **Employee**, **Employment**                     | Read access to worker or personnel records                     |
    | **Compensation**, **Payroll Run**                | Payroll module access                                          |
    | **Benefit**, **Dependent**, **Benefit Coverage** | Benefits module access                                         |
    | **Time Off**, **Timesheet Entry**                | Time and attendance module access                              |
    | **Bank Info**, date of birth, national ID        | Sensitive personal data, granted separately from employee read |
    | Cost center, department                          | The specific field group or report definition                  |

    **Result:** The specific access to request.

    <Note>
      A missing sensitive-data grant raises no error. The connector authenticates cleanly,
      the model loads, and those fields come back null.
    </Note>
  </Step>

  <Step title="Send the customer their setup guide">
    The [setup guide](https://help.bindbee.dev) carries per-system click paths and is white-labeled, so the one for their platform can go straight to the administrator.

    **Result:** They know where to click in their own system.
  </Step>

  <Step title="Resync once the permission is granted">
    Permission changes apply from the next run onwards. Trigger a fresh one to pull the newly readable models or fields.

    **Result:** The next sync includes what was refused.
  </Step>
</Steps>

### When the error doesn't make sense

Origin systems return their own error text, and some of it is opaque even to the people who administer those systems daily. Ask Bindbee what it means.

<Warning>
  An upstream `403` means the credentials your customer authorized lack a permission, rather
  than Bindbee refusing your request. Checking your own API keys will not find it.
</Warning>

## Alerting

The `connector_sync_error` webhook event fires when a model fails, so you hear about it without polling - see [Monitoring this programmatically](/guides/troubleshooting/sync-status#monitoring-this-programmatically).

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="The administrator says the permission is already granted">
    Check the permission sits on the account the connector authenticated as, rather than the administrator's own. Integration users get provisioned with a narrower role than the person configuring them.

    Some platforms require the integration user to be reactivated, or a token reissued, before a change takes effect.
  </Accordion>

  <Accordion title="The failure appears on some runs but not others">
    Intermittent permission errors indicate token scope changing between refreshes, or a source system applying limits under load. Capture the timestamps of both a succeeding and a failing run before escalating.
  </Accordion>

  <Accordion title="Records return but a specific field is still null">
    Fetch the raw payload to see whether the value arrived at all - see [Inspect raw data](/guides/reading-writing/raw-data). A value present in `raw_data` and absent from the unified response is a mapping question, and you can surface it as a [custom field](/guides/extending/custom-fields).
  </Accordion>

  <Accordion title="The integration connects over SFTP rather than an API">
    File-based connectors fail differently: SFTP credentials and the files the source system drops govern access, in place of API scopes. A missing field points at the file layout.
  </Accordion>

  <Accordion title="Every model failed, not just one">
    That's the credential itself rather than a permission on it - see [Connector relink](/guides/troubleshooting/connector-relink).
  </Accordion>
</AccordionGroup>

## Related

* [Sync status](/guides/troubleshooting/sync-status) - the step before this one
* [Logs](/guides/troubleshooting/logs) - the last resort, when no error explains what you're seeing
* [Connector relink](/guides/troubleshooting/connector-relink) - when every model fails at once