Every failed TripWorks API request returns a stable error code you can branch on. Reading the code, not the message, keeps your integration working when wording changes, because the message is written for people and can be reworded at any time. This article explains what an error response contains, which codes you will meet most often, and what to do about each.

What does an error response look like?

A response always includes a success boolean. When a request fails, it also includes a human-readable message and a structured error object with a stable code. The message is written for people and its wording can change. The code is written for your software and stays the same, so branch on the code.

{
  "success": false,
  "message": "The key doesn't have the scope this request needs.",
  "error": { "code": "insufficient_scope" }
}

Which error codes will you meet?

These are the codes you will see most often, and what to do about each:

• insufficient_scope (status 403). The key is valid but doesn't have permission for this object. Edit the key's permissions. See How API keys and access work.
• too_many_requests (status 429). The key or the account went over an allowance. Pause, retry with a growing delay, and fetch less. See Build integrations that stay fast and efficient.
• validation_failed (status 422). A value in your request isn't valid. The response lists each field that failed, so you can show or fix each one.
• unknown_fields. The request includes a field TripWorks doesn't accept for that operation. Remove it, or check its spelling in the API reference.
• not_found. The record you asked for doesn't exist.
• decision_required (status 409). Not a failure. TripWorks needs a choice from you before it can finish, and nothing was changed. See How decisions work in the REST API.

Two more cases return a status without a record-level code: a request with no key or a malformed key gets a 401, and a filter or sort the object doesn't support gets a 422.

When you are tracking down a failure, note the request ID. Every request has one, and it's how you and TripWorks support find exactly what was sent and returned.

Examples

• Branch on the code. When a request fails, read error.code. Pause on too_many_requests, fix permissions on insufficient_scope, and show the field errors on validation_failed.
• Show the user what to fix. On validation_failed, list each failed field next to the matching input in your own screen.
• Retry with patience. On too_many_requests, wait, then retry with a growing delay instead of resending straight away.
• Catch a typo early. An unknown_fields reply names a field the endpoint doesn't accept, which usually means a misspelled field name.
• Keep a trail. Log the request ID with every failure so support can find the exact request quickly.

Frequently asked questions

Related

• How decisions work in the REST API
• Get started with the REST API
• Build integrations that stay fast and efficient
• How API keys and access work