Errors · Schedulinq Docs

Every refusal of the API is a problem in the RFC 9457 format, sent as application/problem+json. One field tells you what went wrong: code. This page lists every code the API can send, with what to do about it.

The problem

{
  "type": "https://docs.schedulinq.com/en/api/errors#errors.api.insufficientScope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This API key does not have the scope this operation needs.",
  "instance": "/api/v1/users",
  "code": "errors.api.insufficientScope",
  "requestId": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e0b",
  "requiredScope": "users:read"
}

Field	What it holds
`type`	A link to the code's entry on this page.
`title`	The HTTP status's name.
`status`	The HTTP status code.
`detail`	An English sentence for a person reading the log.
`instance`	The request's path, without the query string.
`code`	The code: what to branch on.
`errors[]`	On a refused field: one entry per field, with `field`, `code` and `message`. At most 50; `truncated: true` when there were more.
`requestId`	The request's id.
`requiredScope`	On a 403 `errors.api.insufficientScope`: the scope the key lacks.

Branch on code, and on the code of each errors[] entry — never on title, detail or message. Those are English sentences, and their wording may change.

Every answer carries an X-Request-Id header. Send your own (1 to 128 characters of A-Z, a-z, 0-9, ., _ and -) and it comes back; otherwise you get one. Quote it when you write to support@schedulinq.com.

Status codes

The API answers 400, 401, 402, 403, 404, 405, 409, 413, 415, 422, 429 and 500. A 404 is also the answer for an id that belongs to another organisation. A very large burst can be answered with a 503 before it reaches the API: retry it with backoff.

A refusal is replayed

A refused POST replays its refusal for 24 hours to a retry with the same Idempotency-Key. Fix the cause, then send a new key. See Idempotency.

Authentication and limits

`errors.api.apiKeyMissing`

401

Send your API key in the Authorization header: Authorization: Bearer sq_live_...

Send the key as Authorization: Bearer sq_live_…. See Authentication.

Returned by: every endpoint

`errors.api.apiKeyInvalid`

401

The API key is not valid. Check that you copied the whole key.

Check that the whole key arrived, without spaces or line breaks.

Returned by: every endpoint

`errors.api.apiKeyRevoked`

401

This API key has been revoked. Ask an admin of the organisation for a new key.

An admin revoked the key. Ask for a new one; retrying will not help.

Returned by: every endpoint

`errors.api.apiKeyExpired`

401

This API key has expired. Ask an admin of the organisation for a new key.

The key passed its last valid day. Ask an admin for a new one.

Returned by: every endpoint

`errors.api.insufficientScope`

403

This API key does not have the scope this operation needs.

requiredScope names the scope the key lacks. An admin creates a key that has it.

Returned by: every endpoint

`errors.api.forbidden`

403

This API key may not do this.

`errors.api.tooManyFailedAuthentications`

429

Too many failed authentications from this address. Wait for the number of seconds in Retry-After before trying again.

Wait for Retry-After, then fix the key before you try again. A valid key is never refused by this limit.

Returned by: every endpoint

`errors.api.rateLimitExceeded`

429

Too many requests for this API key. Wait for the number of seconds in Retry-After and try again.

Wait for Retry-After and retry with the same Idempotency-Key. See Rate limits.

Returned by: every endpoint

`errors.api.customerInvitationLimit`

429

This customer has received the maximum number of invitations through the API for now. Try again later.

Wait for Retry-After. Ten invitations to one customer a day is plenty; more usually means a loop in your system.

Returned by: POST /api/v1/invitations

`errors.api.colleagueInvitationLimit`

429

The organisation has sent the maximum number of colleague invitations through the API for now. Wait for the number of seconds in Retry-After and try again.

Wait for Retry-After. Repeats count too, so do not retry in a tight loop.

Returned by: POST /api/v1/users, POST /api/v1/users/invitations/{id}/resend

`errors.api.requestTooLarge`

413

The request body is larger than 256 KB.

No API request needs this much. Check what your system puts in the body.

Requests the API cannot route or read

`errors.api.resourceNotFound`

404

There is no resource at this path.

Check the path against the reference.

Returned by: POST /api/v1/users/invitations/{id}/resend

`errors.api.methodNotSupported`

405

This path does not support this HTTP method. The Allow header lists the methods it does support.

`errors.api.mediaTypeNotSupported`

415

Send the request body as application/json and accept application/json.

Send Content-Type: application/json.

`errors.api.badRequest`

400

The request could not be processed.

`errors.api.invalidRequestBody`

400

The request body is not valid JSON.

`errors.api.invalidParameter`

400

A parameter has a value of the wrong type.

Returned by: GET /api/v1/users, POST /api/v1/users, GET /api/v1/services, GET /api/v1/roles, POST /api/v1/planning-links, GET /api/v1/invitations, POST /api/v1/invitations, GET /api/v1/appointments

`errors.api.missingParameter`

400

A required parameter is missing.

`errors.api.unexpectedError`

500

Something went wrong on our side. Try again later; if it keeps happening, contact support with the requestId.

Retry with backoff. If it keeps happening, send the requestId to support@schedulinq.com.

Returned by: every endpoint

Not found and conflicts

`errors.api.appointmentNotFound`

404

This appointment does not exist, or it belongs to another organisation.

Also the answer for another organisation's id.

Returned by: GET /api/v1/appointments/{id}

`errors.api.invitationNotFound`

404

This invitation could not be found.

Also the answer for another organisation's id.

Returned by: GET /api/v1/invitations/{id}

`errors.api.colleagueNotFound`

404

No colleague of this organisation has this id or e-mail address.

Check the id or e-mail address with GET /api/v1/users.

Returned by: POST /api/v1/planning-links, POST /api/v1/invitations

`errors.api.serviceNotFound`

404

This service does not exist, or it is archived.

Check the id with GET /api/v1/services.

Returned by: POST /api/v1/planning-links, POST /api/v1/invitations

`errors.api.customerNotFound`

404

No customer of this organisation has this id.

Also the answer for an archived customer and for another organisation's id. A customer that was merged into another is followed to that one, not refused.

Returned by: POST /api/v1/planning-links, POST /api/v1/invitations

`errors.api.colleagueNotActive`

409

This colleague can't be booked: they have not accepted their invitation yet, or they are deactivated, archived or not schedulable.

The team member has not accepted their invitation yet, or is deactivated or archived. After fixing it, send a new Idempotency-Key: the same key replays this refusal for 24 hours.

Returned by: POST /api/v1/planning-links, POST /api/v1/invitations

`errors.api.customerDeactivated`

409

This customer is deactivated and can't book online. Reactivate them in Schedulinq first.

Reactivate the customer in Schedulinq, then send a new Idempotency-Key.

Returned by: POST /api/v1/invitations

`errors.api.conflict`

409

The resource was changed by another request at the same time. Try again.

Retry with the same Idempotency-Key; this refusal is not stored.

Team members and seats

`errors.api.colleagueArchived`

409

An archived colleague of this organisation has this e-mail address. Restore them in Schedulinq, or invite with another address.

Restore the team member in Schedulinq, or invite with another address.

The problem

Status codes

A refusal is replayed

Authentication and limits

Requests the API cannot route or read

Not found and conflicts

Team members and seats

Idempotency

Validation