Docs
Dashboard

Errors

Every Scrumball API error response uses the same JSON envelope: success is false, code carries the HTTP status and message a short explanation. The sections below cover what each status means, what commonly triggers it and how to resolve it.

Error Response Shape

json
{
  "success": false,
  "code": 400,
  "message": "Bad Request"
}

400Bad Request

What it means

The server could not parse or accept the request, so it was rejected before reaching any business logic.

Common causes

  • The request body is not valid JSON (POST endpoints such as search or monitor task creation).
  • Content-Type is not set to application/json.
  • A query parameter has the wrong format, for example a date not in the required format.
  • A typo in the path hit the wrong route.

How To Fix

  1. Check that the request path and HTTP method match the endpoint reference page.
  2. For POST endpoints, confirm the request carries Content-Type: application/json.
  3. Run the body through a JSON validator to confirm it parses.
  4. Go through the Required Parameters table on the endpoint page and check each parameter name and format.

401Unauthorized

What it means

The request is missing a valid API key, so the server cannot identify the caller.

Common causes

  • The Authorization header was not sent.
  • A Bearer prefix was added in front of the key (this API takes the raw key, no prefix).
  • The key was deleted or rotated and the client is still using the old value.
  • The key picked up a space or line break when it was copied.

How To Fix

  1. Confirm the header is exactly Authorization: YOUR_API_KEY with no prefix.
  2. Check under Dashboard > API Keys that the key is still enabled.
  3. If the key is no longer valid, create a new one and update the server-side environment variable.
  4. Verify connectivity with GET /api/ping first, then debug the specific business endpoint.

403Forbidden

What it means

The caller was identified, but the account is not allowed to use this endpoint or its quota is exhausted.

Common causes

  • The current plan does not include this endpoint (for example audience insights or realtime endpoints).
  • The trial quota has been used up.
  • The subscription has expired.
  • The endpoint is not yet enabled for this account.

How To Fix

  1. Check the remaining quota under Dashboard > Usage.
  2. Confirm the subscription status and which endpoints the plan covers under Dashboard > Billing.
  3. To unlock higher-tier endpoints, upgrade the plan or contact support.
  4. Tell 403 and 429 apart: 403 is a permission problem, 429 is a rate limit.

404Not Found

What it means

The request path does not exist, or the requested resource has no record in the database.

Common causes

  • The endpoint path is misspelled or has been deprecated.
  • The HTTP method does not match (for example a GET request to a POST endpoint).
  • The creator account is not covered by the persistent database.
  • The video or post has been deleted or set to private.

How To Fix

  1. Check the full path and method against the endpoint reference page.
  2. Make sure the Base URL is https://openapi.scdata.cc, not the documentation site domain.
  3. If an account cannot be found, call the matching realtime endpoint to trigger a live fetch.
  4. Distinguish 404 from a 200 response with data: null - the latter means the path is right but there is no data.

429Too Many Requests

What it means

The request rate exceeded the limit allowed by the current plan and the server throttled the call.

Common causes

  • Too many concurrent requests at once.
  • A batch job without throttling sent a burst of requests in a short window.
  • Several service instances share one key without coordinating their call rate.
  • Retry logic has no backoff, so immediate retries after a failure amplify the load.

How To Fix

  1. Reduce concurrency and cap the number of requests per unit of time.
  2. Implement exponential backoff: wait 1 second first, then double each time, up to a recommended ceiling of 32 seconds.
  3. For batch workloads, consume from a queue so the rate stays under control.
  4. Review the usage curve under Dashboard > Usage to locate the peak periods.

500Server Error

What it means

The server hit an unexpected exception while handling the request; the request itself is not at fault.

Common causes

  • An upstream platform data source is temporarily unavailable.
  • An internal server exception.
  • A specific parameter combination triggered an unhandled edge case.

How To Fix

  1. Retry with backoff; the error usually clears after a short wait.
  2. Record the full request context: path, all parameters, request time and response body.
  3. If the same request keeps failing, contact support with that context.
  4. Handle 5xx and 4xx differently on the client: 5xx can be retried, 4xx needs the request fixed.