Troubleshooting common issues

To fix Postman errors with Tallyfy’s API, check the X-Tallyfy-Client header first, verify your authentication grant type is password (not client_credentials), and make sure tokens haven’t expired. These three issues cause most Tallyfy API failures.

Authentication errors

401 Unauthorized

Here are the most common causes, in order of likelihood:

Missing X-Tallyfy-Client header
```
X-Tallyfy-Client: APIClient
```
Every request needs this header. It’s how Tallyfy identifies the client type making API calls.
Wrong grant type
- You used: grant_type=client_credentials
- You need: grant_type=password
- Client credentials grant is only for system-level app operations (tokens last 7 days). For user-context work, always use the password grant.
Expired token
- Access tokens from the password grant last 6 months (not 1 hour)
- Refresh tokens last 12 months
- Client credentials tokens last 7 days
- If you’re unsure, just re-authenticate and get a fresh token

Bearer token format

// Wrong formats:
Authorization: Bearer[token]       // no space
Authorization: Bearer  [token]     // double space
Authorization: [token]             // missing Bearer

// Correct (exactly one space):
Authorization: Bearer [token]

400 Bad request on /oauth/token

The token endpoint requires URL-encoded form data, not JSON:

Wrong content type:

// You have:
Content-Type: application/json

// You need:
Content-Type: application/x-www-form-urlencoded

Wrong body format:

// Wrong - JSON body:
{
    "grant_type": "password",
    "username": "user@example.com"
}

// Right - URL-encoded:
grant_type=password&username=user@example.com&password=...&client_id=...&client_secret=...

Invalid client errors

“Invalid client” or “Client authentication failed” means:

Non-numeric client_id - The API validates that client_id is numeric. If it’s not, you’ll get a 401 with {"error": "invalid_client"}.
Credentials don’t match - Client ID and Secret must be from the same app registration, and the Organization ID must match.
Special characters in secrets - If a secret contains +, /, or =, make sure they’re properly URL-encoded when sent as form data.

Data and request errors

404 Not found

The API returns two different 404 messages depending on the cause:

Wrong URL path returns: {"error": true, "message": "API endpoint not found", "code": "ENDPOINT_NOT_FOUND"}
Missing resource returns: {"error": true, "message": "Resource not found", "code": "RESOURCE_NOT_FOUND"}

Common path mistakes:

// Wrong: /organization/  (singular)
// Right: /organizations/ (plural)

// Wrong: /templates/     (doesn't exist)
// Right: /checklists/    (the actual endpoint)

// Wrong: /processes/     (doesn't exist)
// Right: /runs/          (the actual endpoint)

// Wrong: /members/       (doesn't exist)
// Right: /users/         (the actual endpoint)

Wrong Organization ID - Make sure you’re using the org ID, not a user ID. Log what you’re sending:

console.log("Org ID:", pm.environment.get("TALLYFY_ORG_ID"));
console.log("Full URL:", pm.request.url.toString());

422 Unprocessable entity

This means validation failed. The API returns errors in this format:

{
    "error": true,
    "errors": {
        "field_name": ["The field_name is required."]
    }
}

Common causes:

Missing required fields (e.g., name when launching a process)
Wrong data types (sending "100" as a string instead of 100 as a number)
Invalid date format (use YYYY-MM-DD)
Invalid enum values for select/radio fields

403 Forbidden

This typically means the authenticated user or client app doesn’t have permission for the requested resource. For client credentials specifically, the API checks that the token’s client app belongs to the same organization as the one in the URL. If the org doesn’t match, you’ll get "You don't have application's permissions for this organization!".

Rate limiting

429 Too many requests

Tallyfy’s API rate limit is 600 requests per minute per authenticated user (or per IP for unauthenticated requests). This resets on a rolling 1-minute window, not on the hour.

Trial accounts have additional rate limits on specific operations (like password updates: 3 per day).

When rate limited, the API returns:

{
    "message": "You've reached the limit for [operation]. Please try again later.",
    "code": "RATE_LIMIT_EXCEEDED"
}

The response includes Retry-After and X-RateLimit-Remaining headers.

Simple backoff approach:

// If you get a 429, wait for the Retry-After header value
if (pm.response.code === 429) {
    const retryAfter = pm.response.headers.get("Retry-After");
    console.log(`Rate limited. Wait ${retryAfter} seconds before retrying.`);
}

Spacing out batch requests:

// Add a delay between requests to stay under limits
async function processItemsWithDelay(items, delayMs = 150) {
    for (const item of items) {
        await pm.sendRequest({...});
        await new Promise(resolve => setTimeout(resolve, delayMs));
    }
}

File upload issues

Files not uploading

Wrong body type - file uploads must use form-data, not raw JSON:

Body: form-data
  - name: [File type, select your file]
  - uploaded_from: [Text, e.g., "ko_field" or a form field ID]
  - subject_type: [Text, "Template" or "Process"]
  - subject_id: [Text, the template or process ID]

File too large - Tallyfy’s upload limit is 100MB.

Don’t set Content-Type manually - When using form-data in Postman, let Postman set the Content-Type header automatically (it needs to include the boundary string). Manually setting Content-Type: multipart/form-data breaks the upload.

Debugging helpers

Pre-request debug script

Add this to your collection’s Pre-request Script to catch issues before they happen:

// Check required headers
const headers = pm.request.headers.toObject();

if (!headers['Authorization']) {
    console.error("MISSING: Authorization header");
}
if (!headers['X-Tallyfy-Client']) {
    console.error("MISSING: X-Tallyfy-Client header");
}

// Check required environment variables
['TALLYFY_ORG_ID', 'TALLYFY_ACCESS_TOKEN', 'TALLYFY_BASE_URL'].forEach(key => {
    if (!pm.environment.get(key)) {
        console.error(`MISSING env var: ${key}`);
    }
});

console.log(`Request: ${pm.request.method} ${pm.request.url.toString()}`);

Response analysis script

Add this to your Tests tab for automatic error diagnosis:

const statusCode = pm.response.code;

if (statusCode >= 400) {
    console.error(`Error ${statusCode}: ${pm.response.status}`);

    try {
        const body = pm.response.json();

        if (body.message) {
            console.error(`Message: ${body.message}`);
        }
        if (body.errors) {
            console.error("Validation errors:");
            Object.entries(body.errors).forEach(([field, msgs]) => {
                console.error(`  ${field}: ${Array.isArray(msgs) ? msgs.join(', ') : msgs}`);
            });
        }
    } catch (e) {
        console.error("Response body:", pm.response.text());
    }
}

// Log rate limit status
const remaining = pm.response.headers.get("X-RateLimit-Remaining");
if (remaining !== null) {
    console.log(`Rate limit remaining: ${remaining}`);
}

Getting help

Before contacting support

Open the Postman Console (View > Show Postman Console) and check the full request/response details
Verify all three required headers are present: Authorization, X-Tallyfy-Client, and Accept
Confirm your org ID and token are valid
Check the response body for specific error messages and codes

Include these details in any support request:

Exact error message and HTTP status code
Full request URL (with method)
Response body
Your organization ID
Timestamp of the attempt

Useful resources

Postman > Authentication setup for Postman

Set up Tallyfy API authentication in Postman using OAuth 2.0 with the password grant type. Store…

Api Clients > Getting started with Postman API testing

Test Tallyfy’s REST API in Postman without writing code. Authenticate with the password grant…

Postman > Postman collection organization

Organize Postman collections around Tallyfy’s API resources with folder prefixes and consistent…

Open Api > API integration guide

Tallyfy’s REST API lets you connect workflow features to external systems using OAuth 2.0…

Was this helpful?

Get in touch

About Tallyfy