Skip to main content

Partner API: Reference (Errors, Rate Limits, Regions)

Error envelope and codes, rate limits, and region codes.

Errors

Errors use a consistent envelope with a stable machine-readable type:

{
  "errors": [
    {
      "type": "org_not_owned_by_partner",
      "code": 403,
      "message": "Organization not found or not owned by this partner"
    }
  ]
}

HTTP

Type

Meaning

400

validation_error

Request body or query failed validation (details in message)

400

org_id_mismatch

X-Org-Id header, path and/or token disagree, or the X-Org-Id header is missing

400

unsupported_protocol

SSO protocol other than saml (for example oidc); contact support if you need it

401

invalid_partner_key

Missing, malformed, unknown or revoked partner key

401

invalid_access_token

Missing, malformed, unknown or expired access token. Tokens also become invalid the moment the partner key that minted them is revoked.

403

ip_not_allowed

Request IP is not in your allowlist (applies to organization-scoped calls too)

403

org_not_owned_by_partner

Organization does not belong to your account

404

not_found

Resource does not exist in this organization. Unknown paths and unsupported methods also return not_found with the message Unknown endpoint, without requiring a credential.

409

conflict

The request conflicts with current state: a duplicate externalId, employeeId or group name, a deactivated organization, employees managed by an HRIS or SFTP integration, an import already in progress, or an update to a terminated employee

429

rate_limited

Too many requests — see Retry-After

500

server_error

Something went wrong on our side

503

rate_limit_unavailable

The rate-limiting service is temporarily unavailable; retry shortly

Rate limits

Limits are applied in a rolling 1-second window:

  • Partner API key: 20 requests/second per key

  • Organization access token: 10 requests/second per organization. The bucket is shared by every live token for that organization, so two tokens minted for the same organization do not double the limit.

Exceeding a limit returns 429 rate_limited with a Retry-After header in seconds (currently always 1). Higher limits are available on request.

Region codes

GET /regions | Partner API key

{
  "data": [
    { "code": "CA", "name": "California", "country": { "code": "US", "name": "United States" } },
    { "code": "ON", "name": "Ontario", "country": { "code": "CA", "name": "Canada" } }
  ]
}

This endpoint is the authoritative list of region codes accepted in purchasedRegions. Codes are bare, not prefixed with a country: today they cover US states and territories (CA, NY, TX, PR …) and Canadian provinces (AB, BC, ON, QC …). Codes not in this list are rejected with 400 validation_error.

Partner API documentation:

Related Articles
Did this answer your question?