Signature Verification Keeps Returning 401: Check Order, Timezone, and Whitespace First

Nail Down These 3 Questions Before Writing Code

Before integrating a sports data API, there are three questions you need to align on with product and operations. Skip this and you'll be redoing work no matter how much code you write. They don't involve the signature algorithm itself, but they directly determine what data you pull, how you cache it, and how you handle degradation.

Coverage scope. Do you need football, basketball, or both? Are you covering only the top five leagues, or also cup matches, qualifiers, and youth tournaments? This determines how you pass the sport and league parameters in your requests, and whether a match you never built a display template for suddenly shows up in your schedule list. We've seen teams go live only to discover the API returns women's matches and the frontend truncates the team names. Confirm the coverage list with your contact person as the very first thing after registering — don't wait until integration and guess from return values.

Real-time requirements. Is score push at the second level, minute level, or just post-match stats? These three needs map to completely different integration approaches. Second-level goes through WebSocket or long-connection subscriptions, minute-level can poll REST, and post-match stats just pull from historical endpoints. A lot of 401 debugging time is actually wasted on "I subscribed, why is there no data?" — only to find out you subscribed to event A but polled event B. Write the real-time requirement into your technical plan before you start coding.

Historical depth. How far back do you need? A week, a season, or three years? Historical data storage and query endpoints are usually separate from real-time ones — authentication might be the same but parameters differ. If the product needs "last ten head-to-head matches," confirm whether the API can query history by two team IDs instead of you accumulating data yourself. Ask this during registration, or data migration later will be expensive.

Once these three are locked down, you can determine: which environment to use, which set of endpoints to call, and which parameters the signature covers. Now let's get into the actual flow.

Minimum Working Path: Register → Key → First REST Call → Real-time Subscription

Don't start by writing the full business logic. Get a minimal path working first, isolating the three variables — signature, timezone, and encoding — for verification.

Step one, register and get your key. Go to the developer platform at https://dev.apiballs.com/#/user_register to register, then grab your app_id and app_secret from the console. Note: the secret is shown in full only once at creation; after that the console only displays the prefix. If you didn't save it, you'll have to reset. We recommend storing it in your team's password manager — don't paste it into chat logs.

Step two, confirm the environment domain. Test and production environments use different domains, and possibly different keys. Many 401s happen because someone used a test key against the production domain. The console will indicate which environment each key is bound to — double-check it.

Step three, send your first REST request. Pick an endpoint that doesn't depend on real-time data, like "match list" or "team info." These have few parameters, making the signature easy to verify. The request typically includes: app_id, timestamp, sign, and business parameters.

Step four, verify real-time subscription. Once REST works, try subscribing. Subscription authentication usually happens during the handshake, with the same signature rules as REST, but a shorter timestamp validity window. If REST works but subscription doesn't, first check whether the handshake parameters are missing sign or timestamp.

The path is working when you can see in your logs: one complete set of request parameters, one successful response, and one subscription heartbeat. Keep these three log entries — you'll rely on them for all future debugging.

First Call Example (With Illustrative Request)

Below is an illustrative request for verifying the signature structure. Check your console docs for the actual parameter names — this only demonstrates order and encoding.

POST /v1/match/list HTTP/1.1
Host: api.example-sports.com
Content-Type: application/json
X-App-Id: your_app_id
X-Timestamp: 1710000000
X-Sign: 3f8a...c2d1

{
  "sport": "football",
  "date": "2025-03-15",
  "page": 1,
  "page_size": 20
}

The common signature string concatenation order is: app_id + timestamp + business params sorted by key in lexicographic order + app_secret. Watch out for these traps:

• If business parameters contain nested JSON, confirm whether it's flattened or signed as a whole. Both rules exist — check the docs.
• Do null-value parameters participate in signing? Some endpoints require filtering out null and empty strings, others require keeping them. This is the easiest place to get it wrong.
• Is the timestamp in seconds or milliseconds? The docs will say, but many people copy sample code without changing it.
• After concatenating the signature string, do you hash directly or URL-encode first? Reversing the order gives a completely different result.

A practical verification method: print the signature string locally and compare it character by character against the doc's example. If there's no example, send two requests with the same parameters and check whether the signature is stable. If it's unstable, a timestamp or random number is involved. If it's stable but you get 401, the concatenation rule is wrong.

# Illustrative: signature string concatenation (order per docs)
params = {"sport": "football", "date": "2025-03-15", "page": 1}
sorted_items = sorted(params.items())
raw = app_id + str(timestamp) + "".join(f"{k}{v}" for k, v in sorted_items) + app_secret
sign = hashlib.md5(raw.encode("utf-8")).hexdigest()

The key here isn't the algorithm — it's sorted and str(timestamp). We've seen teams concatenate with the millisecond value of timestamp, which doesn't match the server's second value, resulting in a persistent 401.

The Two Most Common 4xx: Signature and Timezone

401 and 403 are the two most common status codes during integration. 401 usually means signature verification failed; 403 is a permissions or coverage issue. We'll only cover 401 here.

Timezone issues. The timestamp itself is Unix time and carries no timezone. But if you generate the date parameter using your local timezone while the server parses it as UTC, you'll query the wrong data — or even trigger a signature failure due to a date format mismatch. For example, if you write 2025-03-15 in UTC+8, the server might still be on 2025-03-14 in UTC. The fix: generate all date parameters in UTC, or explicitly include a timezone offset in the request. If your logs show date and timestamp don't match, check here first.

Whitespace and encoding. If the signature string contains spaces, Chinese characters, or special characters, the encoding must match the server's. A common mistake is the client URL-encoding parameters while the server signs with raw values — or vice versa. Another case: a parameter value has a trailing space that's invisible to the eye but changes the signature. When debugging, print the signature string with repr() to spot hidden characters.

Parameter order. Lexicographic order isn't "the order in your code" — it's ASCII order. Uppercase letters come before lowercase, digits before letters. If parameter names mix underscores and camelCase, the order is easy to get wrong. Check against the order table in the docs rather than guessing.

The key itself. If you've ruled out everything above, then suspect the key. Check for extra spaces, copy-paste errors, or using a test key against production. After key rotation, the old key usually has a brief grace period, but once it expires you'll get 401. The console shows the last-used time for each key — compare and you'll know if you used the wrong one.

Heartbeat, Idempotency, and Retraction: Must-Haves for Real-time Subscriptions

Real-time subscriptions require a different debugging approach than REST. REST is one request, one response; subscriptions are long connections, and problems usually aren't 401 but "connected but no data."

Heartbeat. Most subscription protocols require the client to send periodic heartbeats, and the server responds in kind. If the client doesn't send them, the server may disconnect after 30 seconds to 2 minutes. On reconnect, if the signature timestamp has expired, you'll get 401. So the heartbeat interval must be shorter than the server timeout, and you must regenerate the signature on reconnect. If your logs show "connection established → no messages → disconnect → reconnect 401," check the heartbeat first.

Idempotency. Subscription push messages may be duplicated, especially after network jitter and reconnection. The client should deduplicate using message IDs — don't just write every message to the database. We've seen cases where scores were double-counted because idempotency wasn't implemented. The message ID is usually in the push body, possibly named event_id or seq — check the docs.

Retraction. Score data has retraction scenarios: a goal disallowed by VAR, an event's attribution changed. Subscription protocols usually have retract or revoke message types. When the client receives these, mark the previous event as invalid rather than deleting it. The frontend should display it with a "cancelled" state overlay. If you only append and never retract, users will see goals that never happened.

// Illustrative: subscription message handling skeleton
ws.onmessage = (msg) => {
  const data = JSON.parse(msg.data);
  if (data.type === "heartbeat") return;
  if (seen.has(data.event_id)) return; // idempotency
  seen.add(data.event_id);
  if (data.type === "retract") {
    markAsRetracted(data.event_id); // retraction
  } else {
    upsertEvent(data);
  }
};

Heartbeat, idempotency, and retraction — write these into your code on day one of integration, not after launch. By the time you patch them in, you'll usually already have a batch of dirty data.

Troubleshooting Table: Symptom / Cause / How to Check

Here's a table of common symptoms for quick reference during integration. It's ordered from outside in: check the request itself first, then the signature, then the key and environment.

In this table, "intermittent 401" is most easily misdiagnosed as a key problem. In reality, a few minutes of client clock drift will expire the timestamp. Run ntpd or chrony on your servers, and in containers watch out for host time synchronization.

Three Things to Do Before Going Live

First, encapsulate the signature logic into a standalone module — input parameters, output signature — rather than scattering it across requests. That way you only need to look in one place when debugging. Second, log the full signature string (after masking sensitive parts), but never log the key. When a 401 occurs, comparing the signature string against the doc example is more useful than staring at the status code. Third, prepare a "minimal request" script that sends a single request with fixed parameters, to quickly determine whether it's an environment issue or a business logic issue.

When integrating a sports data API, signature and timezone are two hurdles you can't avoid. Lock down the debugging sequence for both, and 401 stops being mysterious. Full Speed Data's developer platform is at https://dev.apiballs.com/#/user_register — register, get the minimal path working first, then expand your business logic. It saves time compared to doing it the other way around.