Errors and versioning

Error envelopes, concurrency failures, and v2 compatibility.

Strave API errors use one consistent shape, and the major version stays stable for the lifetime of v2. This page explains both.

Error response

Every REST error uses the same envelope:

{
	"error": {
		"code": "not_found",
		"message": "The resource was not found.",
		"requestId": "019c...",
		"details": {}
	}
}

When you contact support, include the requestId.

Status codes

The API uses these HTTP status codes for errors:

Status	Meaning
`400`	The request or required idempotency key is invalid.
`401`	Authentication is missing or invalid.
`403`	A scope, permission, entitlement, or active Installation is missing.
`404`	The resource does not exist inside the authorized target.
`409`	The command conflicts with current state or a prior idempotent request.
`412`	The `If-Match` revision is stale.
`413`	The request body is larger than the route accepts.
`428`	A required `If-Match` header is missing or invalid.
`429`	A quota or rate limit was reached.
`503`	A required service is unavailable.

Versioning policy

The major version is part of the URL. Within v2, Strave can add new endpoints, optional fields, webhook types, and enum values. Your client must accept these additions without failing.

These changes need a new major version:

Removing or renaming a field.
Changing the type of a field.
Changing established behaviour.