Errors and status codes

Standard response envelope, status codes, and error-handling expectations for the D-Sports API.

Response envelope

All API routes return a consistent JSON envelope.

Success (HTTP 2xx):

{
  "success": true,
  "data": { /* route-specific payload */ }
}

Error (HTTP 4xx / 5xx):

{
  "success": false,
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE"
}

The code field is a stable, machine-readable identifier you can use for programmatic error handling. Common codes are listed below.

Common status codes

Status	Code	Meaning
200	—	Successful read or mutation.
400	VALIDATION_ERROR	Invalid payload or missing required fields.
401	UNAUTHORIZED	Authentication missing or invalid.
403	FORBIDDEN	Authenticated but insufficient permissions.
404	NOT_FOUND	Resource not found.
409	CONFLICT	State conflict such as a duplicate handle.
429	RATE_LIMITED	Too many requests — back off and retry.
500	INTERNAL_ERROR	Unexpected server-side failure.

Error handling guidance

• Check the top-level success field before accessing data.
• Use the code field for programmatic branching (e.g. retry on RATE_LIMITED, prompt re-auth on UNAUTHORIZED).
• Treat writes as retriable only when idempotency is guaranteed by the route.
• Surface the error message in client logs for operational debugging.

Where to verify

Route-specific responses are defined in the OpenAPI endpoint docs under the API Reference > Endpoints group.