Lydira API
TR

Guides

Errors

Every refusal names a code. Branch on the code, not on the status: three different 403s want three different fixes.

The envelope

Errors are always JSON and always carry error and code. A 422 additionally carries details, which maps each rejected attribute to its reasons so a client can put the message next to the field that caused it.
422
{
  "error": "Validation failed",
  "code": "validation_failed",
  "details": {
    "email": ["is invalid"],
    "name": ["can't be blank"]
  }
}

401Authentication

  • unauthorizedfix first

    No key, or the token does not resolve to one.

  • key_revokedfix first

    The key existed and was switched off. Issue a new one.

  • key_expiredfix first

    The key passed its expiry date. Issue a new one.

403Permission

  • ip_not_allowedfix first

    The credential is fine, the source address is not on the key's allowlist.

  • plan_upgrade_requiredfix first

    The account's plan does not include API access at all.

  • insufficient_scopefix first

    The key is narrow and this endpoint is outside it.

  • forbiddenfix first

    The role bound to the key does not permit this operation.

  • plan_gatedfix first

    The plan does not include this particular report.

  • misconfiguredfix first

    The account has no active owner for the key to act as. The agency must fix this.

  • traveler_scopefix first

    A traveller token was presented outside its own routes.

404Not found

  • not_foundfix first

    No such record, or it belongs to another account.

  • unknown_entityfix first

    The import entity key is not in the registry.

409Conflict

  • idempotency_conflictretry

    The first call with this key is still running. Wait out `Retry-After` and repeat.

422Rejected

  • validation_failedfix first

    The record was rejected. `details` names the fields.

  • idempotency_key_reusefix first

    That key was already used for a different body or path.

  • entity_not_writablefix first

    The entity broadcasts and can be read, but cannot be pushed.

  • no_rowsfix first

    The ingest body carried no rows.

  • too_many_rowsfix first

    The batch is over the per-request row ceiling. Split it.

  • no_companyfix first

    The account has no company to file the rows against.

  • unknown_branchfix first

    The `branch_id` is not one of this account's. `GET /api/v1/workspace` lists them.

  • invalid_stagefix first

    No such lead stage.

  • conversion_failedfix first

    The lead could not be converted. Usually it already was.

503Temporary