Getting started

Errors

Every error response is an RFC 7807 problem document. Switch on type — title is for humans and may change wording.

Shape

Served with Content-Type: application/problem+json. type is the stable identifier you should branch on. title is a short human-readable summary. status mirrors the HTTP status. instance is the request id (the X-Request-Id you sent, or one the gateway generates) and is always present.

{
  "type":   "https://gateway/errors/editing-locked",
  "title":  "Editing is no longer allowed on this job",
  "status": 409,
  "instance": "req_01HX…"
}

Catalog

https://gateway/errors/invalid-body

400

Request body failed to parse or didn’t match the expected shape.

https://gateway/errors/invalid-query

400

One or more query parameters failed validation.

https://gateway/errors/invalid-path

400

A required path parameter (e.g. a job or site ID) was missing.

https://gateway/errors/unknown-custom-field

400

A key sent under custom_fields isn’t available to your integration.

https://gateway/errors/project-not-in-scope

400

The project ID you sent isn’t one you can use.

https://gateway/errors/customer-not-in-scope

400

The customer ID you sent isn’t one you can use.

https://gateway/errors/field-not-writable

400

A field in the body isn’t writable for your integration.

https://gateway/errors/unauthorized

401

Missing, invalid, or insufficiently scoped bearer key.

https://gateway/errors/no-scope

403

Your key has no customers attached yet. Contact us to finish setup.

https://gateway/errors/not-found

404

The job or site doesn’t exist, or isn’t accessible to your key.

https://gateway/errors/editing-locked

409

The job has progressed past the editable states. Contact your scheduling team to change it.

https://gateway/errors/cancellation-locked

409

The job is past the point where it can be cancelled via the API.

https://gateway/errors/multi-customer-create-unsupported

409

Your key spans multiple customers; job creation needs a single-customer scope.

https://gateway/errors/state-not-configured

422

state=open|closed was used but your tenant has no open/closed statuses configured.

https://gateway/errors/no-projects-configured

422

A project is required to create a job, but your key has none in scope.

https://gateway/errors/job-type-required

422

No job_type was sent and your tenant has no default job type configured.

https://gateway/errors/invalid-request

422

FieldInsight rejected the upstream request (status mirrors FieldInsight — usually 422, sometimes 400).

https://gateway/errors/rate-limited

429

You’ve exceeded the budget. Back off and retry after ~1–2 seconds with jitter.

https://gateway/errors/internal

500

Something went wrong on our side. Retry; if it persists, contact us with the request ID.

https://gateway/errors/not-implemented

501

A planned endpoint that isn’t live yet (e.g. job photos — coming soon).

https://gateway/errors/upstream-scope-violation

502

Upstream response was rejected before reaching you, for safety.

https://gateway/errors/schema-drift

502

Upstream response didn’t match the expected shape. Retry; if it persists, contact us.

https://gateway/errors/writes-disabled

503

Writes aren’t enabled for your integration yet. Contact us.

https://gateway/errors/cancel-not-configured

503

Cancellation isn’t enabled for your integration yet. Contact us.