Errors

We use normal HTTP status codes. Read the status first, and then the body.

Status codes on the API routes

Status	What it means	What to do
400	A parameter, header or body is not valid	Fix the request
401	The key is missing or not valid	Check the key. See A good key that gets a 401.
403	Your integration does not have this route, filter or sort	Ask your contact
404	The venue is not available to your key	Check the id
409	The request conflicts with the current state. See the code.	See Safe retries
413	The body is too large	Send a smaller batch
429	You went over a limit	See Rate limits
500	Something went wrong on our side	Try again later, and tell us with the X-Request-Id
503	A service we need is down for a moment	Try again with a wait

What an error looks like

Most errors look like this. message can be one text or a list of texts.

{
  "statusCode": 400,
  "message": "skip cannot be used with cursor pagination",
  "error": "Bad Request"
}

The import routes add a stable code, and an errors list for validation problems. In errors, the entries of your request are counted from 0.

{
  "statusCode": 400,
  "code": "CONCIERGE_ENTRY_IMPORT_VALIDATION_FAILED",
  "message": "Concierge entry import validation failed.",
  "errors": [
    {
      "path": "[1].phoneNumber",
      "code": "MATCHES",
      "message": "phoneNumber must use canonical E.164 format."
    }
  ]
}

Use code when it is there. The text in message can change.

Status codes on the venue routes

The venue routes answer 400 for a bad key, not 401.

Status	Body	What it means
400	"Token is required"	No token header
400	"Invalid token" or "Unable to validate token"	The key is not valid
400	"Venue ID is required"	This route needs a venue key, and you sent a publisher key
400	["lastSyncedAt must be a string"]	lastSyncedAt is missing
400	["Invalid Date"]	lastSyncedAt is not in the right format
400	["lastSyncedAt must not be older than 15 days"]	Your checkpoint is too old. See Keep your data in sync.

Request ids

Every answer from /external/v1 has an X-Request-Id header. You can send your own value in that header (letters, numbers, dots, dashes and underscores, up to 128 characters) and we use it. Include it when you report a problem.

Errors on orders, reservations and guests

These three routes answer every error in one shape:

{
  "error": {
    "type": "not_found",
    "code": "venue_not_found",
    "message": "A venue in venueIds does not exist or is not available to this key.",
    "param": "venueIds",
    "requestId": "6f1c..."
  }
}

Match on code. message is for people and can change. param names the parameter when the error is about one. A database or Redis problem answers 503, also while we check your key, so a 401 always means the key itself. 429 and 503 come with a Retry-After header in seconds.

Status	type	code	What to do
400	invalid_request	validation_failed	A parameter has a wrong value. See param.
400	invalid_request	unknown_parameter	This route does not take that parameter. Check the spelling.
400	invalid_request	conflicting_filters	Send updatedSince or createdSince, not both.
400	invalid_request	invalid_cursor	Send a nextCursor with the same filters it came with.
401	authentication_failed	invalid_credential	The key is missing, wrong or no longer active.
403	permission_denied	not_provisioned	The key does not have this route or field. Ask your Speakeasy contact.
404	not_found	venue_not_found, order_not_found, reservation_not_found, guest_not_found	It does not exist, or your key cannot read it.
429	rate_limited	rate_limit_exceeded	Wait for Retry-After seconds.
503	service_unavailable	backend_unavailable	Wait for Retry-After seconds and try again.
500	internal_error	internal_error	Something went wrong on our side. Send us the requestId.