Volleyball API responses and errors

Responses and errors

Every answer is JSON in one of two shapes: data and meta when it worked, an error object when it did not. Error codes are words, and every error links to the page that explains it.

When it works

data holds what you asked for: a list, or one object. meta holds your plan, counts, pages and the next cursor.

200 application/json

{
  "data": [
    {
      "id": "cp_mmra2w7x",
      "name": "FIVB Beach Volleyball World Championships",
      "discipline": "beach",
      "gender": "men",
      "season": 2027,
      "start_date": "2027-08-13",
      "end_date": "2027-08-22",
      "country_code": "NL"
    },
    {
      "id": "cp_v15a0yfs",
      "name": "FIVB Beach Volleyball World Championships",
      "discipline": "beach",
      "gender": "women",
      "season": 2027,
      "start_date": "2027-08-13",
      "end_date": "2027-08-22",
      "country_code": "NL"
    }
  ],
  "meta": {
    "plan": "Complete",
    "count": 2,
    "next_cursor": "eyJvIjoyLCJwIjoyfQ",
    "page": 1,
    "per_page": 2,
    "total": 9291,
    "total_pages": 4646,
    "next_page": 2,
    "prev_page": null
  }
}

When it does not

code is a word you can switch on, message says what to change, docs links here. When another plan would answer, plan and pricing say which.

403 application/json

{
  "error": {
    "code": "upgrade_required",
    "message": "/v1/matches/live is on the Live and Complete plans.",
    "plan": "Live",
    "pricing": "https://volleyballapi.com/pricing",
    "docs": "https://volleyballapi.com/documentation/live"
  }
}

Every error

HTTP	Code	When
400	`bad_request`	A value of the wrong shape, a key sent in the address, or a required parameter left out
401	`unauthorized`	No key, or a key that is not known or was revoked
403	`upgrade_required`	Your plan does not include this endpoint or this day; the answer names the plans that do
404	`not_found`	No endpoint at that address, or no match, competition, team or player with that id
405	`bad_request`	A method other than GET
422	`unknown_parameter`	A parameter the endpoint does not take; the answer lists the ones it does
429	`rate_limited`	Too many calls this minute; Retry-After says when to try again
429	`quota_exceeded`	The day's or month's allowance is used; the answer says when it resets
500	`server_error`	Our fault; it is logged and looked at

Values

Times are UTC in ISO 8601 with a Z. date and time_local are the venue's own calendar day and clock. A value we do not have is null, never left out, so every object of a kind has the same keys.

PreviousAuthentication NextPagination