Skip to content
Tallyfy

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:

  1. 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.

  2. 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.

  3. 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

  4. 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:

  1. 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"}.
  2. Credentials don’t match - Client ID and Secret must be from the same app registration, and the Organization ID must match.
  3. 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 not, 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

  1. Open the Postman Console (View > Show Postman Console) and check the full request/response details
  2. Verify all three required headers are present: Authorization, X-Tallyfy-Client, and Accept
  3. Confirm your org ID and token are valid
  4. 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 the password grant type with environment variables, the required X-Tallyfy-Client header, and automatic token refresh for uninterrupted API testing.

Api Clients > Getting started with Postman API testing

Set up Postman with Tallyfy’s REST API to test workflow automation endpoints including OAuth authentication with the password grant type, required headers, and common operations like launching processes and completing tasks.

Postman > Collection organization best practices

Organize Postman collections for Tallyfy’s API by grouping requests by resource type using folders for workflows and implementing consistent naming conventions with bracket prefixes like [SETUP] [CORE] and [UTILS] to help team members quickly identify purpose and access levels while reducing errors and speeding up integration development.

Open Api > API integration guide

The Tallyfy REST API enables workflow automation through two authentication methods (user-based tokens obtained from Settings or application-based OAuth credentials) requiring specific headers and proper token management while supporting multi-organization contexts and webhook integrations with standardized date formats.
Get in touch
About Tallyfy