---
title: Debug API Requests
slug: debug-api-requests
type: how-to
plugin: huxx-connect
summary: Diagnose failing API requests with the shortcode debug attribute and the Logs screen, and recognize the most common failure signatures.
keywords: [debug, logs, errors, troubleshooting, request logs]
version_added: 1.2.5
version_updated: 1.2.5
level: intermediate
related: [display-data-with-shortcodes, extract-values-with-keys, cache-endpoint-responses, shortcodes, template-functions]
---

When a shortcode renders nothing, or a PHP call returns an error, HuxxConnect
gives you two diagnostic tools: the shortcode's `debug` attribute for a quick
on-page look, and the **Logs** screen for the full request/response record.

> **Quick version:**
> 1. Add `debug="true"` to the shortcode:
>    `[huxx_api api_id="demo_api" endpoint_id="get_products" debug="true"]`,
>    then reload the page while logged in as an administrator.
> 2. Read the error panel — `code`, `message`, and `context` name the failure.
> 3. For full detail, go to **HuxxConnect → Logs**, filter by **Status**, and
>    click the failing row to expand its request and response.
> 4. Remove `debug="true"` before publishing the page.

## Turn on shortcode debug output

By default a failed request renders as **empty output** — site visitors never
see error details. That is the production behavior you want, but it makes
diagnosis blind. The `debug` attribute turns the details on.

**Who sees what — read this before publishing.** `debug="true"` is a
diagnostic switch, not a display option:

- **Configuration errors** — unknown `api_id`, unknown `endpoint_id`, or a
  deactivated API — render the debug panel **only for administrators** (users
  with the `manage_huxx_connect` capability). Site visitors still see empty
  output.
- **HTTP errors returned by the remote API** render the debug payload as JSON
  for **anyone viewing the page** while the attribute is set. The payload
  includes the full request URL and the API's raw response — so if the API
  uses API Key auth with the key in the query string, the
  [credential](/docs/connect/explanation/glossary/#credentials) appears in
  plain text to every visitor. Removing `debug="true"` before publishing is
  mandatory, not merely tidy.

So the working pattern is: add the attribute, reload while logged in, read
the panel, fix the problem, remove the attribute. (Behavior verified in
`src/Frontend/Shortcodes.php` and `src/Core/Executor.php`.)

Shortcode:

```
[huxx_api api_id="demo_api" endpoint_id="get_products" debug="true"]
```

Output when the request fails (here, the endpoint path points at a URL that
returns 404):

```
{
    "_huxx_connect_error": true,
    "code": 404,
    "message": "API Error (HTTP 404)",
    ...
}
```

`message` carries the error text the API returned when the response body has
a recognizable message field (`message`, `error`, `detail`, and similar);
otherwise it falls back to `API Error (HTTP <status>)`.

Two errors are always visible regardless of `debug`, because the shortcode
cannot execute at all: leaving out a required attribute renders
`HuxxConnect: "api_id" attribute is required.` (or the same for
`endpoint_id`) for every viewer — a signal you'll spot immediately.

:::novice
An HTTP status code is the three-digit result number every
web server sends with its response: 2xx means success, 4xx means the
request was wrong (bad path or credentials), 5xx means the server itself
failed. Background: [How HuxxConnect works](/docs/connect/explanation/how-huxxconnect-works/).
:::

## Debug in PHP

The same switch exists for [template functions](/docs/connect/reference/template-functions/):
pass `'debug' => true` and HTTP-request errors come back as an array you can
log. Configuration errors — unknown API or endpoint, a deactivated API —
remain `ErrorResponse` objects even with the flag, and without it every
error is an `ErrorResponse` object. The helper functions accept both forms.

```php
$result = huxx_api( 'demo_api', 'get_products', array( 'debug' => true ) );

if ( huxx_api_is_error( $result ) ) {
    $error = huxx_api_get_error( $result );
    error_log( 'DummyJSON request failed: ' . $error['code'] . ' ' . $error['message'] );
}
```

Log output:

```
DummyJSON request failed: 404 API Error (HTTP 404)
```

## Inspect the Logs screen

Every request is logged automatically — no setting to enable. Go to
**HuxxConnect → Logs**.

<!-- screenshot-todo: logs--expanded-row--error-detail | alt: Request Logs screen with a failed request row expanded showing request URL, headers, and error message -->

Narrow the list with the filter bar:

- **API** — limit to one API.
- **Endpoint** (Pro) — limit to one endpoint of the selected API.
- **Status** — buckets: **Success (2xx)**, **Redirect (3xx)**,
  **Client Error (4xx)**, **Server Error (5xx)**, **Transport Error (0)**.
  Transport errors are requests that never got an HTTP response — timeout,
  DNS, SSL, or connection failures.
- **Trigger** — what fired the request: **PHP function**, **Shortcode**, or
  **Admin test** (the **Run Test** button). Pro adds its own trigger types.
- **From** / **To** — date range.
- **Search** (Pro) — match against URL or error message.

Each row shows Time, API, Endpoint, Method, URL, Status, Duration, and
Source. Click a row to expand the detail panel: **Request URL**,
**Request Headers**, **Error**, **Request Body**, and **Response Body** —
usually everything you need to reproduce the request outside WordPress.

Housekeeping: **Export CSV** and **Export JSON** (both Pro) download the
current filtered list; **Delete Selected** and **Clear All Logs** remove entries.
Old entries are purged automatically after the **Log Retention (days)**
setting in **HuxxConnect → Settings** (1–365 days).

## Common failure signatures

| Signature in Logs | Likely cause | Fix |
|---|---|---|
| Status 408, `Request timed out. Consider increasing the timeout setting.` | Slow API or low timeout | Raise the API's **Timeout (seconds)** or the **Default Timeout (seconds)** in Settings |
| Transport error, `DNS resolution failed. Please verify the API URL is correct.` | Typo in the base URL | Correct the API's base URL |
| Transport error, `SSL certificate verification failed. Check the SSL settings or the API's certificate.` | Broken or self-signed certificate | Fix the certificate, or review the SSL verification setting in **HuxxConnect → Settings** |
| Status 503, `Connection refused. The API server may be down or unreachable.` | API host down or blocking your server | Check the API's status page; try the URL from the server |
| Client Error 401 / 403 | Wrong, expired, or missing credentials | Re-check the auth setup — see [Authentication Types](/docs/connect/reference/authentication-types/) |
| Client Error 404 | Wrong endpoint path or path variable value | Verify the path — see [Use path variables](/docs/connect/how-to/use-path-variables/) |
| Success (2xx) in Logs but the page shows nothing | `keys` path doesn't match the response shape | Inspect **Response Body** in the log detail, then fix the path — see [Extract values with keys](/docs/connect/how-to/extract-values-with-keys/) |

One more subtle case: the page shows *old* data rather than an error. If the
log shows a failure but the page still renders, the stale-cache fallback
served the last good response — see
[Cache endpoint responses](/docs/connect/how-to/cache-endpoint-responses/).

## If it didn't work

- **The debug panel doesn't appear.** For configuration errors the panel is
  restricted to administrators — log in with an account that has the
  `manage_huxx_connect` capability and reload. Also confirm the attribute is
  exactly `debug="true"`; any other value is treated as off.
- **The request never shows up in Logs.** The shortcode probably never
  executed: a missing `api_id`/`endpoint_id` renders a visible message
  instead of calling the API, and a cached response is served without a new
  request. Change a query parameter or shorten the cache duration to force a
  live request.
- **Log entries you saw yesterday are gone.** Retention purged them — raise
  **Log Retention (days)** in **HuxxConnect → Settings**, or export
  (Pro) before they age out.