Errors

Every error returns the same JSON shape:

{
    "message": "This API key is missing the required scope: accounts.write.",
    "code": "missing_scope"
}

Branch on code, never on message. The code is a contract and will not change. The message is written for humans and gets reworded whenever we can word it better.

Some errors add fields alongside those two. They are always additive, so a client reading only code keeps working.

Status codes #

Validation errors #

A 422 adds an errors object keyed by field, in Laravel's standard shape:

{
    "message": "The given data was invalid.",
    "code": "validation_failed",
    "errors": {
        "username": ["The username field is required."],
        "proxy_id": ["The selected proxy id is invalid."]
    }
}

Plan limits #

When your subscription plan does not cover what you asked for, you get a 403 with the plan that would:

{
    "message": "Your plan does not include the CSFloat marketplace.",
    "code": "plan_limit_reached",
    "plan": {
        "heading": "CSFloat is not in your plan",
        "upgrade_url": "https://dashboard.steamlabs.dev/subscription"
    }
}

This is the one error worth handling specially, because it is not transient and retrying never fixes it. Surface plan.upgrade_url to whoever is running your integration.

The Steam account cap and the proxy cap use the same code rather than one of their own, and add the numbers so your client can say how far over it is (max_steam_accounts on the account cap, max_proxies on the proxy cap):

{
    "message": "Your plan covers 25 Steam accounts.",
    "code": "plan_limit_reached",
    "plan": {
        "heading": "Account limit reached",
        "upgrade_url": "https://dashboard.steamlabs.dev/subscription",
        "max_steam_accounts": 25,
        "remaining": 0
    }
}

GET /api/v1/me tells you your limits up front, so a well-behaved client rarely sees this at all.

Maintenance #

While SteamLabs is under platform maintenance, endpoints that create new work (tasks, listings, trade sends) refuse with a 503:

{
    "message": "This action is paused while SteamLabs is under maintenance. Work already running is unaffected; try again once maintenance ends.",
    "code": "maintenance_mode",
    "reason": "Scheduled worker upgrades, back within the hour"
}

Unlike plan_limit_reached, this is transient: nothing about your request or plan is wrong, and the same call succeeds once maintenance ends. reason is the note the team wrote when enabling it, and can be null. There is no Retry-After header because the end time is not known.

Reads, cancels and deletes keep working throughout, and so do deliveries, settlements and confirmations for sales already made. GET /api/v1/me reports maintenance up front in its maintenance block, so a client can check before firing.

Every code #

Authentication #

Requests #

Conflicts #

There is no generic conflict code. A 409 always names what is in the way, so your client can tell "wait for a task to finish" apart from "you already have one of these".

The first six clear on their own: poll the work that holds the resource, then try again. The last three describe state you have to change yourself, so retrying alone never helps. idempotency_key_in_flight is the one remaining 409, and it is in the idempotency table below.

Each endpoint's page lists the conflicts that endpoint can return.

Plan and limits #

Availability #

Idempotency #

Retrying #