Reference

Errors

Find the exact v1 error bodies, the conditions that return them and the headers your client should check before retrying.

Handled v1 errors give back a JSON object holding one error string. Read the HTTP status first, then the body. List requests that succeed and requests for one record that succeed both return 200.

Status and body

The bodies shown here are exact. These errors cover the ten public v1 endpoints.

Status	Error	When
`400`	`{"error":"limit must be a positive integer"}`	A list request has a limit that fails integer parsing or parses to a value below 1.
`400`	`{"error":"Invalid cursor"}`	A list cursor cannot be decoded, or its offset is not a non-negative integer.
`401`	`{"error":"Invalid API key"}`	The bearer key is missing, malformed, unknown, incorrect or revoked. A wrong authorization scheme or token longer than 256 characters also returns this error.
`404`	`{"error":"Session not found"}`	A session id does not identify a public session in the key campaign.
`404`	`{"error":"Entity not found"}`	A character, location, faction or item id does not identify a wiki-visible entry of that type in the key campaign.
`429`	`{"error":"Rate limit exceeded"}`	Any IP, invalid-authentication, key or owner limit rejects the request.
`500`	`{"error":"Failed to fetch sessions"}`	The sessions list query fails.
`500`	`{"error":"Failed to fetch session"}`	The single-session query fails.
`500`	`{"error":"Failed to fetch characters"}`	Either a character list query or a single-character query fails.
`500`	`{"error":"Failed to fetch locations"}`	Either a location list query or a single-location query fails.
`500`	`{"error":"Failed to fetch factions"}`	Either a faction list query or a single-faction query fails.
`500`	`{"error":"Failed to fetch items"}`	Either an item list query or a single-item query fails.
`503`	`{"error":"Public API temporarily unavailable"}`	Saga20 cannot enforce request limits or complete key verification because a required service or configuration is unavailable.

Take ids from the list endpoint that matches. A record that is private, hidden, or from another campaign gives back the same 404 body as a record that is absent.

Request

curl -i "https://app.saga20.com/api/public/v1/sessions/7b1e3f0a-52c4-4d1e-9a2b-3c8f6d1a9e41" \
  -H "Authorization: Bearer $SAGA20_API_KEY"

Response

HTTP/1.1 404 Not Found
Content-Type: application/json

{"error":"Session not found"}

Error headers

A 401 carries WWW-Authenticate: Bearer realm="public-api". A 429 carries the three X-RateLimit-* headers along with Retry-After.

The handled 404 and 500 fetch errors carry rate headers for the key minute window. The handled 400, 401 and 503 responses do not. Go to rate limits for each window and header value.

Authentication error

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="public-api"

{"error":"Invalid API key"}

Choose the next request

Once you get a 400, fix the parameters, and once you get a 401, verify your full current key. On a 404, fetch the list again and make sure the record still shows in this campaign.

On a 429, hold for at least Retry-After seconds. Send 500 and 503 again after longer waits, for a limited count of tries. A 503 does not carry Retry-After. Take an error body you cannot read as a server failure.

The checks for authentication and rate happen ahead of pagination validation. A failed authentication or rate check can thus come before an invalid query parameter.