API Builder — Troubleshooting & Glossary
Common issues you may encounter when building or using custom API integrations, plus a quick-reference glossary of technical terms.
Troubleshooting
| Issue | Why It Happens | Solution |
|---|---|---|
| "Invalid JSON" when analyzing | The pasted JSON has syntax errors — trailing commas, missing quotes, or single quotes instead of double. | Validate your JSON at jsonlint.com before pasting. |
| Endpoint returns empty data | The Root Accessor doesn't match the response, or JSON paths are wrong. | Test the API manually first. Compare the actual response structure to your configured paths. |
| Auth errors at runtime | Credentials are incorrect, expired, or the auth type doesn't match what the API expects. | Verify credentials in the API provider's dashboard. Confirm the auth method matches the docs. |
| Can't find the integration in workflows | The definition is saved, but no credentials have been added. | Go to Integrations, find your integration, and add credentials. |
| Parameter not recognized by API | The parameter name doesn't match the API's expected name exactly (casing matters). | Check the API docs for exact parameter names. userId ≠ user_id. |
| "Unauthorized" error | The API key or token doesn't have permission for this endpoint, or the wrong header is being used. | Check that your key has the required permissions/scopes. Verify the auth header name matches the API docs. |
| Array data comes back as single item | The response path uses [0] instead of [*]. | Edit the output field's Source JSON Path and replace [0] with [*]. |
| Fields have confusing auto-generated names | Multiple fields have similar names, causing prepended prefixes. | Edit the Node Output Label to any name that makes sense for your workflow. |
Glossary
| Term | Definition |
|---|---|
| API (Application Programming Interface) | A set of rules that lets two systems communicate. In this context, a web API that accepts HTTP requests and returns data. |
| REST (Representational State Transfer) | An architectural style for APIs that uses standard HTTP methods and URLs to access resources. |
| Endpoint | A specific URL path + HTTP method combination that performs one operation (e.g., GET /users). |
| Base URL | The root address of an API, shared by all its endpoints (e.g., https://api.example.com/v1). |
| HTTP Method | The action type of a request: GET (read), POST (create), PUT (update), DELETE (remove). |
| JSON (JavaScript Object Notation) | A text-based data format using key-value pairs, objects {}, and arrays []. The standard response format for REST APIs. |
| Path Parameter | A variable embedded in the URL path, wrapped in curly braces: /users/{id}. |
| Query Parameter | A key-value pair appended to the URL after ?: /users?limit=10. |
| Bearer Token | An access token sent in the Authorization: Bearer <token> header. Common in OAuth 2.0 flows. |
| API Key | A unique string that identifies and authorizes your application when calling an API. |
| Root Accessor | A JSON path that tells the system where the actual data starts inside a wrapper object. |
| Leaf Field | A JSON value that is not an object or array — a string, number, or boolean. The actual data you extract. |
| Group Field | A JSON object or array that contains other fields. |
Wildcard [*] | In JSON path notation, means "every item in this array" — used to extract a field from every element. |
| Credential Schema | The template that determines what fields are shown when a user adds credentials (API key, token, or username/password). |
Related Resources
| Goal | Guide |
|---|---|
| See all built-in integrations | Integrations |
| Learn about workflow nodes | Workflow Nodes |
| Understand AI workflow nodes | AI Platform Features |
| Manage token costs for AI | Usage & Tokens |
| Security & data handling | Security & Privacy |
| Return to API Builder overview | Overview |