What status codes does the Firsty API return?

Standard HTTP semantics: 2xx success, 4xx client error (with a JSON error body), 429 rate limit, 5xx retry with backoff.

The short answer

The Firsty API follows standard HTTP semantics. Every non-2xx response includes a JSON error body with a

code

and

message

Free sandbox. Real Tier-1 carriers. 60 seconds from signup to credentials.

Code	Meaning	What to do
200	Success	Use the body
201	Resource created	Store the returned reference
202	Accepted, processing async	Poll or wait for webhook
400	Bad request	Fix your payload; do not retry blindly
401	Token invalid or expired	Re-mint OAuth2 token
403	Forbidden for this client	Check plan permissions
404	Resource not found	Verify the reference exists
409	Conflict (e.g. duplicate idempotency key)	Treat as success if same payload
422	Validation error	Inspect `errors[]` in the body
429	Rate limited	Back off using `Retry-After` header
500	Server error	Retry with exponential backoff
503	Carrier or partner down	Retry; do not refund the customer yet

json
{
  "code": "plan_not_found",
  "message": "No plan exists with reference plan_eu_5gb_30d",
  "errors": []
}

Always log the

code

field. It is stable across versions;

message

is not.

Was this helpful?