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.

Being over the account cap #

Holding more Steam accounts than your plan covers is a state you can end up in without doing anything: a plan downgrade or an expiry lowers the cap, and nothing is ever deleted to make your fleet fit it. While you are over the cap, every endpoint that starts new work returns plan_limit_reached, whatever the task type:

{
    "message": "You have 2,500 Steam accounts and your plan covers 100. No new tasks can be started until you remove 2,400 of them or move to a plan that covers your fleet.",
    "code": "plan_limit_reached",
    "plan": {
        "heading": "You are over your account limit",
        "upgrade_url": "https://dashboard.steamlabs.dev/subscription"
    }
}

Nothing else changes. Your accounts, their items and their history stay exactly as they were, reads keep working, tasks already queued run to completion, and deliveries, settlements and confirmations for sales already made keep flowing. Remove accounts with DELETE /api/v1/accounts/bulk or move up a tier, and normal service resumes immediately.

Compare steam_accounts_used against max_steam_accounts on GET /api/v1/me to detect this before you fire.

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. So does the last one, on Steam's clock rather than yours. The three before it 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 #