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.
  • Codes in the 2xx range indicate success.
  • Codes in the 4xx range indicate a client-side error (e.g., a problem with the request itself, authentication, or permissions).
  • Codes in the 5xx range indicate a server-side error.
When an error occurs (any 4xx or 5xx code), 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.
  • 400 Bad Request
    • Cause: The server could not process the request due to a client error, such as malformed JSON, invalid syntax, or missing/invalid request parameters.
    • Action: 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
    • Cause: The request lacks valid authentication credentials. This usually means the API key is missing, invalid, or expired in the Authorization header.
    • Action: Ensure you are sending a valid Authorization: Bearer <YOUR_API_KEY> header with an active API key associated with an integration.
  • 403 Forbidden
    • Cause: 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.
    • Action: 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
    • Cause: 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.
    • Action: 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
    • Cause: 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.
    • Action: 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
    • Cause: 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.
    • Action: 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.
  • 429 Too Many Requests
    • Cause: Your application has sent too many requests in a given amount of time and has exceeded the rate limit associated with your API key.
    • Action: Reduce the frequency of your API calls. Check response headers for rate-limiting information and use this information to adjust your request rate to stay within the limits. Consider retrying if indicated (see General Recommendations).

​
💥 Server errors (5xx)

These errors indicate a problem with tipee. 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.
  • 500 Internal Server Error
    • Cause: An unexpected condition was encountered on the server that prevented it from fulfilling the request. This is a general-purpose server error.
    • Action: This is typically a temporary issue. Try the request again after a short delay. If the error persists, it indicates an issue on our side. Please provide details of the request by filling out the bug report form.
  • 503 Service Unavailable
    • Cause: The tipee API is temporarily unavailable due to planned deployment or maintenance on your instance.
    • Action: 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.
  • 504 Gateway Timeout
    • Cause: 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.
    • Action: This is typically a temporary issue. Try the request again after a short delay. If the error persists, it indicates an issue on our side. Please provide details of the request by filling out the bug report form.
  • 507 Insufficient Storage
    • Cause: The tipee instance has run out of storage space needed to complete the request.
    • Action: This is typically a temporary issue. Try the request again after a short delay. If the error persists, it indicates an issue on our side. Please provide details of the request by filling out the bug report form.
  • 508 Loop Detected
    • Cause: tipee encountered a rare concurrency issue while processing the request.
    • Action: 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 attempt to parse the response body for 4xx and 5xx errors, as it contains valuable, specific error messages or codes.
  • Respect Retry-After: If a response includes a Retry-After header, the request should be retried after waiting at least the specified number of seconds.
  • Implement Retries: For potentially transient errors (like 5xx codes or 429), implement a retry strategy (e.g., retrying after increasing delays). For 429 errors, prioritize respecting the rate-limiting headers.
  • Logging: Log your API requests and their responses (especially errors), including status codes, response bodies, and relevant headers to aid in debugging.