Skip to main content
The tipee API uses standard HTTP status codes to indicate the success or failure of an API request. All API requests are atomic: if an error status code (4xx or 5xx) is returned, the request is guaranteed to have had no effect on the system’s state. When an error occurs, the response body contains a JSON object providing more specific details about the error. It’s recommended to parse and log this response body for debugging purposes.

​
Client errors (4xx)

These errors suggest an issue with how the request was constructed or with the permissions of the integration making the call. Generally, these should not be retried without first correcting the underlying issue in the request.
The server could not process the request due to a client error, such as malformed JSON, invalid syntax, or missing/invalid request parameters.What to do: Carefully review your request syntax, parameters, and data types against the API specification for the endpoint you are calling. Check the response body for specific details.
The request lacks valid authentication credentials. This usually means the API key is missing, invalid, or expired in the Authorization header.What to do: Ensure you are sending a valid Authorization: Bearer <YOUR_API_KEY> header with an active API key associated with an integration.
The API key provided is valid, but the associated integration does not have the necessary permissions to access the requested resource or perform the desired action.What to do: Verify the roles and permissions assigned to the integration within the tipee administration interface. Ensure it has the required access level for the target endpoint and resource.
The requested resource could not be found. This usually means the URL path itself is incorrect, or an identifier specified in the request body refers to a non-existent resource.What to do: Double-check the request URL and any resource identifiers used in the request body. Ensure they reference an existing entity in your tipee instance.
The request could not be completed due to a conflict with the current state of the target resource. This often happens when attempting to create a resource that already exists (violating a unique constraint, like an email address) or when trying to update a resource in a way that conflicts with its current state.What to do: Check the current state of the resource. You may need to modify your request to resolve the conflict (e.g., update instead of create, or change the conflicting field).
The request was well-formed (correct syntax and parameters), but the server was unable to process the contained instructions due to semantic errors or failed business logic rules. For example, trying to transition an entity to an invalid state or providing data that violates specific constraints not related to syntax.What to do: Review the data sent in your request body against the business rules and constraints defined for the operation. The response body will often contain specific details about which rule(s) were violated.

​
Server errors (5xx)

These errors indicate a problem on tipee’s side. While your request might be valid, the server could not fulfill it. These errors can often be resolved by retrying the request after a suitable delay.
An unexpected condition was encountered on the server that prevented it from fulfilling the request.What to do: This is typically a temporary issue. Try the request again after a short delay. If the error persists, please provide details of the request by filling out the bug report form.
The tipee API is temporarily unavailable due to planned deployment or maintenance on your instance.What to do: This unavailability is transient and usually lasts only a couple of minutes. Implement a retry mechanism to handle this brief interruption gracefully. If the issue persists for an extended period, check any tipee status pages or fill out the bug report form.
Two operations tried to modify the same data at the same time, and tipee interrupted this one to resolve the conflict. As with any error, the request had no effect: replaying it is safe, including for requests that create or modify data.What to do: Retry the request. The response always includes a Retry-After header, which is a minimum wait rather than a schedule: tipee cannot know how long the competing operation will still run. Wait at least that long, then increase the delay between attempts — for example 1s, 2s, 4s, with a little randomness — and give up after 3 to 5 attempts. Retrying immediately, or repeatedly at the same interval, tends to collide with the very operation that caused the conflict.This error is more likely when several requests touch the same employee at once. Prefer a single request covering a date range over a series of one-per-day calls.If it persists after several attempts, fill out the bug report form.

​
General recommendations

Check the response body

Always parse the response body for 4xx and 5xx errors — it contains valuable, specific error messages.

Respect Retry-After

If a response includes a Retry-After header, wait at least the specified number of seconds before retrying.

Implement retries

For transient errors (5xx and 429), implement a retry strategy with increasing delays.

Log everything

Log your API requests and responses (especially errors), including status codes, response bodies, and relevant headers.