Troubleshoot OpenAI Connections
OpenAI problems can affect different features independently because regular runtime requests and organization usage analytics use different credentials and endpoints.
“OpenAI is not working” can describe several independent failures. A missing regular key affects chat and content tools; a missing Admin key affects only organization analytics; an unsuitable model affects assistant responses; and a failed vector operation affects knowledge without necessarily breaking ordinary chat. Separating those paths is faster and safer than replacing every credential.
The practical starting point is to copy the exact admin or visitor error without copying a secret. Continue through the workflow until you retry once after resolving the cause and review the php log for server-side transport errors, then use the field notes below to understand which choices affected AI output and which only changed delivery, access, or presentation.
What this feature does and when to use it
Section titled “What this feature does and when to use it”Use this sequence before changing unrelated assistant or knowledge settings.
Use this feature in the following situations:
- A model list, chat response, translation, metadata suggestion, file upload, or sync request returns an OpenAI error.
- Normal chat works but cost and usage analytics does not.
- You need to distinguish account, project, billing, model, transport, and knowledge-store problems.
Where to find it
Section titled “Where to find it”Before you begin
Section titled “Before you begin”- SmartSite Assistant is installed and activated.
- You are signed in with an account that can manage WordPress options.
Set it up step by step
Section titled “Set it up step by step”- Copy the exact admin or visitor error without copying a secret.
- Confirm the regular API key is present and masked.
- Open Assistants and verify the model list loads.
- Check project access, billing, rate limits, and model availability in the OpenAI account.
- If only Usage & Costs fails, verify the Admin API Key and optional Project ID.
- If only knowledge fails, inspect vector-store and per-item sync errors.
- Retry once after resolving the cause and review the PHP log for server-side transport errors.
Fields, controls, and important values
Section titled “Fields, controls, and important values”These checks help separate a connection problem from an answer-quality problem. Credentials and project settings determine whether requests are accepted; model compatibility affects whether a particular operation can run; synchronization errors affect what knowledge can be retrieved. Once the connection succeeds, continue troubleshooting instructions, sources, and retrieval instead of repeatedly replacing a valid key.
| Field, control, or status | What SmartSite Assistant does with it | How to use it and why it matters |
|---|---|---|
| Regular API Key | Used for nearly all runtime and content-management OpenAI operations. | Treat “Regular API Key” as a secret connection value. Redact it everywhere, confirm it belongs to the same account as the related identifiers, and use a controlled test to distinguish successful storage from successful authentication. |
| Admin API Key | Used only for organization usage/cost endpoints. | “Admin API Key” is only for organization usage and cost reporting; visitor chat continues to use the regular key. Its broader reporting access makes careful storage, masking, and dashboard permissions especially important. |
| Project ID | Can make analytics empty or fail when it does not match the Admin key context. | “Project ID” must be the machine identifier or key from the owning system, not a similar display label. Mixing projects, accounts, profiles, or WordPress options can make the form look complete while returning empty or unrelated data. |
| Sync error list | Shows item-specific upload, vector-store, or deletion errors. | “Sync error list” helps locate where the workflow currently stands. Resolve pending or failed items before relying on them, then verify the outcome in a new conversation because earlier context can hide whether fresh content is being used. |
How to confirm it is working
Section titled “How to confirm it is working”Judge Troubleshoot OpenAI Connections where its effect is actually consumed—by the administrator, visitor, model, or connected service. The expected result above is more useful than a green badge because it describes the behavior the configuration was meant to produce.
Practical example
Section titled “Practical example”If chat works but cost cards fail, leave the regular key alone and troubleshoot the Admin key/project fields.
Recommended practice
Section titled “Recommended practice”- Change one part of Troubleshoot OpenAI Connections at a time and keep a short record of the previous value and test result.
- Verify the saved result in the screen, visitor session, or connected service that actually consumes the setting.
Important warnings
Section titled “Important warnings”Common problems and focused checks
Section titled “Common problems and focused checks”| Problem | What to check and what to do next |
|---|---|
| Chat says no active assistant. | Create or activate a local assistant after validating the key. |
| Usage data is stale. | Wait for the one-hour cache window or use the screen refresh control; a failed refresh can retain stale cached data. |
| Troubleshoot OpenAI Connections is missing or does not match this guide. | Confirm the plugin is active and the account can manage WordPress options. Separate credential, project, model, and network failures before changing assistant content. |
| A change on Troubleshoot OpenAI Connections does not produce the expected result. | Keep the exact notice and test case, then review the browser console and WordPress/PHP log. Separate credential, project, model, and network failures before changing assistant content. |
Screen reference
Section titled “Screen reference”- Capture
- Show a sanitized OpenAI error notice together with the OpenAI API tab where credentials remain masked.
- Show
- Error notice, masked credential status, Project ID, Save button
- Viewport
- Desktop, 1440 × 900
- Annotate
- Use numbered callouts only for controls referenced in the procedure.
- Redact
- OpenAI keys, tokens, secrets, personal information, private URLs, IP addresses, and conversation text