> ## Documentation Index
> Fetch the complete documentation index at: https://api.tipee.ch/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Tabs>
  <Tab title="Do not retry">
    <AccordionGroup>
      <Accordion title={<><Icon icon="circle-xmark" /> 400 Bad Request</>} description={<span className="italic text-sm">Malformed JSON, invalid syntax, or missing/invalid parameters</span>}>
        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.
      </Accordion>

      <Accordion title={<><Icon icon="lock" /> 401 Unauthorized</>} description={<span className="italic text-sm">Missing, invalid, or expired API key</span>}>
        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.
      </Accordion>

      <Accordion title={<><Icon icon="ban" /> 403 Forbidden</>} description={<span className="italic text-sm">Valid API key but insufficient permissions</span>}>
        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.
      </Accordion>

      <Accordion title={<><Icon icon="magnifying-glass" /> 404 Not Found</>} description={<span className="italic text-sm">Incorrect URL path or non-existent resource identifier</span>}>
        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.
      </Accordion>

      <Accordion title={<><Icon icon="triangle-exclamation" /> 409 Conflict</>} description={<span className="italic text-sm">Resource state conflict (e.g. duplicate unique constraint)</span>}>
        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).
      </Accordion>

      <Accordion title={<><Icon icon="file-circle-exclamation" /> 422 Unprocessable Entity</>} description={<span className="italic text-sm">Semantic errors or failed business logic rules</span>}>
        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.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Retryable">
    <AccordionGroup>
      <Accordion title={<><Icon icon="gauge-high" /> 429 Too Many Requests</>} description={<span className="italic text-sm">Rate limit exceeded — retry after <code>Retry-After</code> delay</span>}>
        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](/guides-and-resources/rate-limiting) page.
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="Retry after delay">
    <AccordionGroup>
      <Accordion title={<><Icon icon="server" /> 500 Internal Server Error</>} description={<span className="italic text-sm">Unexpected server-side condition — retry after a short delay</span>}>
        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](https://forms.zohopublic.eu/gammadia/form/BugTracker/formperma/D944VhALtU1XJb-4OPU7JwyPi4zTB4ojzLUUgLnBSvw).
      </Accordion>

      <Accordion title={<><Icon icon="plug-circle-xmark" /> 503 Service Unavailable</>} description={<span className="italic text-sm">Planned deployment or maintenance — retry after a couple of minutes</span>}>
        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](https://forms.zohopublic.eu/gammadia/form/BugTracker/formperma/D944VhALtU1XJb-4OPU7JwyPi4zTB4ojzLUUgLnBSvw).
      </Accordion>

      <Accordion title={<><Icon icon="arrows-spin" /> 508 Loop Detected</>} description={<span className="italic text-sm">Rare concurrency issue — retry after <code>Retry-After</code> delay</span>}>
        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](https://forms.zohopublic.eu/gammadia/form/BugTracker/formperma/D944VhALtU1XJb-4OPU7JwyPi4zTB4ojzLUUgLnBSvw).
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Retry directly">
    <AccordionGroup>
      <Accordion title={<><Icon icon="clock" /> 504 Gateway Timeout</>} description={<span className="italic text-sm">Upstream server did not respond in time</span>}>
        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](https://forms.zohopublic.eu/gammadia/form/BugTracker/formperma/D944VhALtU1XJb-4OPU7JwyPi4zTB4ojzLUUgLnBSvw).
      </Accordion>

      <Accordion title={<><Icon icon="hard-drive" /> 507 Insufficient Storage</>} description={<span className="italic text-sm">Instance ran out of storage space</span>}>
        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](https://forms.zohopublic.eu/gammadia/form/BugTracker/formperma/D944VhALtU1XJb-4OPU7JwyPi4zTB4ojzLUUgLnBSvw).
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

## General recommendations

<CardGroup cols={2}>
  <Card title="Check the response body" icon="code">
    Always parse the response body for `4xx` and `5xx` errors — it contains valuable, specific error messages.
  </Card>

  <Card title="Respect Retry-After" icon="hourglass-half">
    If a response includes a `Retry-After` header, wait at least the specified number of seconds before retrying.
  </Card>

  <Card title="Implement retries" icon="rotate">
    For transient errors (`5xx` and `429`), implement a retry strategy with increasing delays.
  </Card>

  <Card title="Log everything" icon="list-check">
    Log your API requests and responses (especially errors), including status codes, response bodies, and relevant headers.
  </Card>
</CardGroup>