Billing & subscribers

The error format#

A real 401

{
  "type": "urn:problem:missing_api_key",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Send your API key in the X-API-Key header. Keys are created in the admin under Settings → API access.",
  "instance": "/api/v1/account",
  "code": "missing_api_key"
}

Field	What it is
`type`	urn:problem:<code>.
`title`	Short summary of the kind of problem.
`status`	HTTP status.
`detail`	What went wrong, for a person.
`instance`	The request path.
`code`	Stable machine-readable code.
`errors`	Per-field problems, for validation_failed.

When fields are wrong, validation_failed lists each one in errors:

400 validation_failed

{
  "type": "urn:problem:validation_failed",
  "title": "Invalid request",
  "status": 400,
  "detail": "Some fields are missing or invalid.",
  "instance": "/api/v1/payments",
  "code": "validation_failed",
  "errors": [
    { "field": "amount", "message": "must not be null" }
  ]
}

422, refused by a business rule

{
  "type": "urn:problem:same_plan",
  "title": "Request refused",
  "status": 422,
  "detail": "The subscriber is already on Home 10 Mbps.",
  "instance": "/api/v1/subscribers/3f2a6c1e-8b7d-4c1a-9e2f-1a2b3c4d5e6f/plan",
  "code": "same_plan"
}

What to do with an error#

When you get	Do this
`429` rate_limited	Wait Retry-After seconds, then retry the same request.
`409` idempotency_in_progress	Your first try is still running. Retry the same request in a few seconds.
`500` internal_error	Retry a read with a growing pause. For a write, retry with the same Idempotency-Key, or read the record back first.
A network error or timeout	Same as a 500: you don't know if it arrived. Retry with the same Idempotency-Key.
`400`, `401`, `403`, `404`, `422`	Don't retry it unchanged. Fix the request, the key or the data first.

Treat a code you don't recognise by its HTTP status. New codes may be added to v1.

Status codes#

Status	Meaning
200 OK	Done. For a write, also when there was nothing to change (already suspended, already active, receipt already recorded).
201 Created	A payment was recorded or an endpoint added.
202 Accepted	Your ISP requires approval for this suspension. A request was filed; nothing has changed yet.
204 No Content	Deleted.
400 Bad Request	The request is malformed or a parameter is invalid.
401 Unauthorized	No key, or the key is wrong, revoked or expired.
403 Forbidden	The key lacks the scope, its creator lacks the permission, or the ISP's account is suspended.
404 Not Found	No such record in your ISP's account, or no such operation.
405 Method Not Allowed	That path doesn't take that method.
409 Conflict	Clashes with a request in progress or an existing record.
415 Unsupported Media Type	Send the body as application/json.
422 Unprocessable	Understood but refused by a business rule. Nothing changed.
429 Too Many Requests	Rate limit reached for this key.
500 Internal Server Error	Something went wrong on our side. It has been logged.

Error codes#

Code	Status	What it means
`invalid_request`	400	A value breaks a rule, for example an amount of zero, or notes missing when reason is OTHER. detail says which.
`validation_failed`	400	Fields are missing or invalid. errors lists each one.
`malformed_body`	400	The body is missing or isn't valid JSON for this operation.
`missing_parameter`	400	A required query parameter is missing.
`missing_header`	400	A required header is missing.
`invalid_parameter`	400	A parameter has a value of the wrong type.
`idempotency_key_required`	400	This operation needs an Idempotency-Key header.
`missing_api_key`	401	No X-API-Key header.
`invalid_api_key`	401	CoreSync doesn't know this key.
`api_key_revoked`	401	The key was revoked.
`api_key_expired`	401	The key passed its expiry date.
`insufficient_scope`	403	The key doesn't have the scope this operation needs.
`key_owner_lacks_permission`	403	The person who created the key doesn't hold the permission behind this operation.
`tenant_suspended`	403	Your CoreSync account is suspended or cancelled.
`tenant_terminated`	403	Your CoreSync account has been terminated.
`not_found`	404	No such record in your ISP's account. A malformed id answers this too.
`no_such_operation`	404	There is no operation at this path.
`method_not_allowed`	405	This path doesn't take this method.
`idempotency_in_progress`	409	A request with this Idempotency-Key is still running. Retry shortly.
`duplicate_reference`	409	This provider and receipt are already recorded for another subscriber.
`unsupported_media_type`	415	The body isn't application/json.
`idempotency_key_reused`	422	This Idempotency-Key was used for a different request. Use a new key for new work.
`invalid_state`	422	The subscriber isn't in a state that allows this, for example suspending one that isn't ACTIVE.
`same_plan`	422	The subscriber is already on that plan.
`plan_inactive`	422	The plan isn't ACTIVE, so it can't be assigned.
`no_subscription`	422	The subscriber has no subscription yet. Assign a first plan in the admin.
`no_active_subscription`	422	There's no active subscription to reactivate. Record a payment instead, which renews it.
`currency_mismatch`	422	The payment isn't in your ISP's currency.
`payment_not_applied`	422	The payment was recorded but couldn't be applied. It's listed as unmatched. Retry with the same Idempotency-Key, or apply it from Payments in the admin.
`suspend_failed`	422	The suspension couldn't be completed. detail says why.
`reactivate_failed`	422	The reactivation couldn't be completed. detail says why.
`plan_change_failed`	422	The plan change couldn't be completed. detail says why.
`approval_unavailable`	422	This action needs approval, and the key has no creator to file the request under. Create the key again from the admin.
`invalid_webhook`	422	The webhook URL or events break a rule, or you already have 10 endpoints. detail says which.
`rate_limited`	429	Too many requests for this key. Wait Retry-After seconds.
`internal_error`	500	Unexpected error on our side. If it was a write, read the record back before retrying.

Each operation in the reference lists the codes it can return.

NextPagination →

Stuck, or missing something? Tell us what you're building.

hello@coresyncisp.com