Authentication, errors and limits

API keys

Every request carries one of your store's secret keys:

curl https://paylead.app/api/v1/store \
  -H "Authorization: Bearer sk_live_your_key"

• Create keys in Settings → Developers → API keys. Only the store owner can.
• Each key works for one store. If you have several stores, each has its own keys.
• The full key is shown once, when you create it. Paylead keeps only a fingerprint of it, so a lost key is replaced, not recovered.
• Keep keys on your server. Anyone with a key can read your orders and customers. Never put one in website code, a mobile app or a public repository.
• Make one key per app, so you can delete one without breaking the others. A store can have up to 10.
• Test keys start with sk_test_ and only see test-mode subscriptions. See Test mode.

GET /store is a quick way to check a key works: it returns the store the key belongs to.

Errors

Paylead uses normal HTTP status codes. Error bodies are JSON with a message for people and, for authentication errors, an error code for your code.

Status	error	What it means
401	missing_api_key	No Authorization: Bearer header
401	invalid_api_key	The key is wrong or was deleted
402	plan_required	The store's plan doesn't include the API. Upgrade to Pro
403	store_suspended	The store is suspended, so its API is off
403	developer_access_blocked	Paylead turned off developer access for this store. Contact support
403	live_key_required	A test key called an endpoint that only works with live keys
404		The thing doesn't exist, or belongs to another store
422		Validation failed. errors lists each field's problems
429		Too many requests. Wait a minute

A validation error looks like this:

{
  "message": "The title field is required.",
  "errors": {
    "title": ["The title field is required."]
  }
}

Some actions return a 422 with an error code when the request is valid but can't be done, for example cancelling a paid invoice (invoice_paid).

Rate limits

Each key can make 120 requests a minute. Past that you get a 429. If you check access on every page load, cache the answer for a few minutes, or use webhooks instead.

Pagination

List endpoints return 25 items a page. Use ?page=2 for more, and ?per_page= to choose up to 100.

{
  "data": [ … ],
  "links": {
    "first": "https://paylead.app/api/v1/orders?page=1",
    "last": "https://paylead.app/api/v1/orders?page=8",
    "prev": null,
    "next": "https://paylead.app/api/v1/orders?page=2"
  },
  "meta": {
    "current_page": 1,
    "last_page": 8,
    "per_page": 25,
    "total": 187
  }
}

Lists are newest first. Single objects come back inside data:

{ "data": { "id": 42, "object": "order", … } }

The access check is the one exception: it returns its answer at the top level, so has_access is easy to read.