# Response Format (/developers/api/responses)



## Response Structure [#response-structure]

API responses include an `ok` field that indicates whether the request succeeded.

### Success Response [#success-response]

When a request succeeds, the API returns `ok: true` along with the requested data:

```json
{
  "ok": true,
  "data": {
    // Your requested data here
  }
}
```

**Response Fields:**

<TypeTable
  type="{
  &#x22;ok&#x22;: { type: &#x22;boolean&#x22;, description: <>{&#x22;Always &#x22;}<code>{&#x22;true&#x22;}</code>{&#x22; for successful requests&#x22;}</>, required: true },
  &#x22;data&#x22;: { type: &#x22;object&#x22;, description: <>{&#x22;The requested resource or response data. The structure varies by endpoint.&#x22;}</>, required: true },
}"
/>

### Error Response [#error-response]

When a request fails, the API returns `ok: false` along with error details:

```json
{
  "ok": false,
  "error": "Human-readable error message"
}
```

**Response Fields:**

<TypeTable
  type="{
  &#x22;ok&#x22;: { type: &#x22;boolean&#x22;, description: <>{&#x22;Always &#x22;}<code>{&#x22;false&#x22;}</code>{&#x22; for failed requests&#x22;}</>, required: true },
  &#x22;ok&#x22;: { type: &#x22;string&#x22;, description: <>{&#x22;Human-readable error message explaining what went wrong&#x22;}</>, required: true },
}"
/>

<Callout type="info">
  Error messages are designed to not contain sensitive information and can be
  safely displayed in user interfaces.
</Callout>

## HTTP Status Codes [#http-status-codes]

The API uses standard HTTP status codes to indicate the general category of response:

| Status Code | Description                                              |
| ----------- | -------------------------------------------------------- |
| `200`       | **OK** - Request succeeded                               |
| `201`       | **Created** - Resource created successfully              |
| `400`       | **Bad Request** - Invalid request parameters             |
| `401`       | **Unauthorized** - Missing or invalid authentication     |
| `403`       | **Forbidden** - Authenticated but lacks permission       |
| `404`       | **Not Found** - Resource doesn't exist                   |
| `409`       | **Conflict** - Request conflicts with current state      |
| `422`       | **Unprocessable Entity** - Validation error              |
| `429`       | **Too Many Requests** - Rate limit exceeded              |
| `500`       | **Internal Server Error** - Server error                 |
| `503`       | **Service Unavailable** - Temporary service interruption |

## Handling Responses [#handling-responses]

Always check the `ok` field to determine if a request succeeded:

```javascript
const response = await fetch("https://api.pandabase.io/stores/{storeId}", {
  method: "GET",
  headers: {
    Authorization: "Bearer sk_xxx",
    "Content-Type": "application/json",
  },
});

const result = await response.json();

if (result.ok) {
  // Success - use result.data
  console.log("data:", result.data);
} else {
  // Error - handle result.error
  console.error(`error ${result.error.code}: ${result.error.message}`);
}
```

<Callout type="idea">
  Include the `X-Request-Id` response header when contacting support so we can find the request.
</Callout>