Error Handling

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.

Range	Meaning
`2xx`	Success
`4xx`	Client-side error (problem with the request, authentication, or permissions)
`5xx`	Server-side error

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.

Do not retry
Retryable

Code	Name	Description
`400`	Bad Request	Malformed JSON, invalid syntax, or missing/invalid parameters
`401`	Unauthorized	Missing, invalid, or expired API key
`403`	Forbidden	Valid API key but insufficient permissions
`404`	Not Found	Incorrect URL path or non-existent resource identifier
`409`	Conflict	Resource state conflict (e.g. duplicate unique constraint)
`422`	Unprocessable Entity	Semantic errors or failed business logic rules

400 Bad 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.

401 Unauthorized

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.

403 Forbidden

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.

404 Not Found

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.

409 Conflict

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).

422 Unprocessable Entity

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.

Code	Name	Description
`429`	Too Many Requests	Rate limit exceeded — retry after `Retry-After` delay

429 Too Many Requests

Your application has sent too many requests in a given amount of time and has exceeded the rate limit associated with your API key.What to do: Reduce the frequency of your API calls. Check response headers for rate-limiting information and use this to adjust your request rate. See also the Rate limiting page.

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.

Retry directly
Retry after delay

Code	Name	Description
`504`	Gateway Timeout	Upstream server did not respond in time
`507`	Insufficient Storage	Instance ran out of storage space

504 Gateway Timeout

The server, while acting as a gateway or proxy, did not receive a timely response from an upstream server it needed to access in order to complete 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.

507 Insufficient Storage

The tipee instance has run out of storage space needed to complete 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.

Code	Name	Description
`500`	Internal Server Error	Unexpected server-side condition — retry after a short delay
`503`	Service Unavailable	Planned deployment or maintenance — retry after a couple of minutes
`508`	Loop Detected	Rare concurrency issue — retry after `Retry-After` delay

500 Internal Server Error

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.

503 Service Unavailable

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.

508 Loop Detected

tipee encountered a rare concurrency issue while processing the request.What to do: This error always includes a Retry-After header. The request should be retried only after waiting for the duration specified in this header. If the error persists after several retries, 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.

Getting Started

​Client errors (4xx)

​Server errors (5xx)

​General recommendations