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

# Error Handling

> Understanding Unifically API error responses

## Response Structure

All Unifically API responses follow a consistent structure:

### Success Response

```json theme={null}
{
  "success": true,
  "code": 200,
  "data": {
    // Response data
  }
}
```

### Error Response

```json theme={null}
{
  "success": false,
  "code": 400,
  "data": {
    "message": "Error message"
  }
}
```

<Note>
  Empty arrays and objects are omitted from responses when not needed.
</Note>

## HTTP Status Codes

| Code  | Meaning               | Description                 |
| ----- | --------------------- | --------------------------- |
| `200` | Success               | Task successfully submitted |
| `400` | Bad Request           | Task generation failed      |
| `401` | Unauthorized          | Invalid or missing API key  |
| `422` | Validation Error      | Invalid request parameters  |
| `429` | Too Many Requests     | Rate limit exceeded         |
| `500` | Internal Server Error | Server error occurred       |

## Error Response Format

When an error occurs, the API returns a simplified structure:

```json theme={null}
{
  "success": false,
  "code": 400,
  "data": {
    "message": "Error message"
  }
}
```

### Response Fields

<ResponseField name="success" type="boolean">
  Indicates whether the request was successful (`true`) or failed (`false`)
</ResponseField>

<ResponseField name="code" type="integer">
  HTTP status code (200, 400, 401, 422, 429, 500)
</ResponseField>

<ResponseField name="data" type="object">
  Response data or error details

  <ResponseField name="message" type="string">
    Human-readable error message (on error)
  </ResponseField>
</ResponseField>

## Example Error Responses

<AccordionGroup>
  <Accordion title="Authentication Failed (401)">
    ```json theme={null}
    {
      "success": false,
      "code": 401,
      "data": {
        "message": "Invalid API key provided"
      }
    }
    ```

    **Solution**: Verify your API key is correct and properly formatted in the Authorization header:

    ```bash theme={null}
    Authorization: Bearer YOUR_ACTUAL_API_KEY
    ```
  </Accordion>

  <Accordion title="Rate Limit Exceeded (429)">
    ```json theme={null}
    {
      "success": false,
      "code": 429,
      "data": {
        "message": "Rate limit exceeded. Please try again later"
      }
    }
    ```

    **Solution**: Implement exponential backoff and respect rate limits
  </Accordion>

  <Accordion title="Validation Error (422)">
    ```json theme={null}
    {
      "success": false,
      "code": 422,
      "data": {
        "message": "Missing required parameter: prompt"
      }
    }
    ```

    **Solution**: Check the API documentation for required parameters and valid values
  </Accordion>

  <Accordion title="Generation Failed (400)">
    ```json theme={null}
    {
      "success": false,
      "code": 400,
      "data": {
        "message": "Task generation failed"
      }
    }
    ```

    **Solution**: Review your request parameters and try again
  </Accordion>

  <Accordion title="Server Error (500)">
    ```json theme={null}
    {
      "success": false,
      "code": 500,
      "data": {
        "message": "Internal server error occurred"
      }
    }
    ```

    **Solution**: Retry the request after a brief delay. Contact support if the issue persists
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Always Check Success Field" icon="check">
    Check the `success` field in every response to determine success or failure
  </Card>

  <Card title="Implement Retry Logic" icon="rotate">
    Retry failed requests with exponential backoff for 429 and 500 errors
  </Card>

  <Card title="Log Errors" icon="file-lines">
    Log all error responses including the error message for debugging
  </Card>

  <Card title="Handle Rate Limits" icon="gauge">
    Implement rate limit handling to avoid 429 errors
  </Card>
</CardGroup>

<Tip>
  Always parse the `error.message` field to provide helpful feedback to your users
</Tip>

<Warning>
  Never expose your API key in client-side code or public repositories
</Warning>