📡 API Calls

API Requests Best Practice.

Tyms exposes a modern and intuitive RESTful API over HTTPS, enabling developers to build robust accounting and finance features into their products. Our API supports all standard HTTP methods:

• GET — Retrieve data
• POST — Create new records
• PUT — Update existing records
• DELETE — Remove records

All requests must be authenticated using your secret API key in the request header. See the Authentication page for details.

---

🔄 Request Rate Limits

To ensure fair use and reliable performance, Tyms enforces rate limits on all API requests:

⏱

Limit: 500 requests per minute per business

If your application exceeds this threshold, Tyms will return a 429 Too Many Requests response. We recommend implementing a retry strategy with exponential backoff.

---

⚙️ Request Requirements

• All requests must be sent over HTTPS

• All payloads (for POST, PUT) must be valid JSON

• Headers must include your API key:

  Authorization: Bearer <your-secret-api-key>
  

---

🧾 Response Format

All responses are returned in standard JSON format, with meaningful status codes and messages to guide you:

JSON

{
  "status": "success",
  "message": "Record created successfully",
  "data": { ... }
}

---

📘 HTTP Status Codes

Tyms follows standard HTTP response codes to indicate the success or failure of API requests. Here’s what each code means and common causes:

Code	Meaning	Description / Possible Cause
200 OK	Success	The request was successful, and the response contains the expected data.
201 Created	Resource Created	A new resource (e.g., invoice, customer) was successfully created.
400 Bad Request	Invalid Input	The request was malformed or missing required fields. Ensure your JSON structure and parameters are correct.
401 Unauthorized	Invalid or Missing API Key	The API key was not provided or is incorrect. Check your authentication header.
404 Not Found	Resource Missing	The requested resource doesn’t exist, or the endpoint URL is incorrect.
429 Too Many Requests	Rate Limit Exceeded	You’ve exceeded the allowed request quota. Pause and retry after some time.
500 Internal Server Error	Server-side Error	Something went wrong on Tyms' servers. Try again later or contact support.

ℹ️

In the event of a 500 error, please include the response and timestamp in your support ticket for faster resolution.

---

📦 Pagination

Endpoints that return lists (like GET /sales) use pagination to keep responses lightweight and efficient.

Query Parameters:

• limit — Number of records per page (default: 10)
• page — Page number to retrieve

Example:

GET /sales?limit=20&page=1

---

✅ Developer Tips

• Use GET for safe read operations, and POST, PUT, DELETE for data mutations.
• Always validate your request payloads before sending them.
• Implement retries and backoff strategies, especially for 429 and 500 errors.
• Use the appropriate environment (sandbox vs production) to prevent data loss.

---

Need help debugging a request? Contact us at [email protected].